13. Test: Scopes

This chapter demonstrates the effect of subsection Preamble.scope in combination with the scope state stack. The goal is to render a Sphinx document for a given target audience, according to the rules defined in Scopes and visibility.

To this end, the objects of module test_scope_mix are rendered once for each target scope, each within its own section of this chapter. The scope is set at the beginning of each section using the directive .. wtrl_push_current_scope::.

The active scope determines which objects are rendered at all, and which references in the resulting HTML artifact are clickable. In this way, a consistent subgraph of the complete set of docstrings of the module is obtained.

The three sections below illustrate how the visible subset of objects changes with increasing scope.

13.1. Scope: Public

Scope below this point is set to public.

Preamble	scope public normative sections Contract, Public classes, Public functions, See also
Contract	general Must represent a public module. Must reference public classes in See_also for testing. Must reference public functions in See_also for testing.
Public classes	X_public, X_extension, X_core
Public functions	f_public, f_extension, f_core
See also	X_public, f_public
Module	test_scope_mix

Classes and functions below this point implicitly belong to package/module test_scope_mix.

Signature	test_scope_mix.f_public( ) -> None
Preamble	scope public normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent a public function. Must reference public classes in See_also for testing.
Parameters
Returns
Raises	<empty>
See also	X_public
Function	f_public

Preamble	scope public normative sections Contract, Public classes, Public methods
Contract	general Must represent a public class. constructor Must be constructible.
Public classes	Y_extension, Y_core
Public methods	m_extension, m_core
Class	X_public

Nested classes in X_public

Public Methods in class X_public

Default module qualifier test_scope_mix ends here. No default module active.

Scope qualifier public ends here. New current scope: public.

13.2. Scope: Extension

Scope below this point is set to extension.

Preamble	scope public normative sections Contract, Public classes, Public functions, See also
Contract	general Must represent a public module. Must reference public classes in See_also for testing. Must reference public functions in See_also for testing.
Public classes	X_public, X_extension, X_core
Public functions	f_public, f_extension, f_core
See also	X_public, f_public
Module	test_scope_mix

Classes and functions below this point implicitly belong to package/module test_scope_mix.

Signature	test_scope_mix.f_public( ) -> None
Preamble	scope public normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent a public function. Must reference public classes in See_also for testing.
Parameters
Returns
Raises	<empty>
See also	X_public
Function	f_public

Signature	test_scope_mix.f_extension( ) -> None
Preamble	scope extension normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent an extension function. Must reference public and extension classes in See_also for testing. Must reference public functions in See_also for testing.
Parameters
Returns
Raises	<empty>
See also	X_public, X_extension, f_public
Function	f_extension

Preamble	scope public normative sections Contract, Public classes, Public methods
Contract	general Must represent a public class. constructor Must be constructible.
Public classes	Y_extension, Y_core
Public methods	m_extension, m_core
Class	X_public

Nested classes in X_public

Preamble	scope extension normative sections Contract
Contract	general Must be constructible. constructor
Class	X_public.Y_extension

Public Methods in class X_public

Signature	test_scope_mix.X_public.m_extension( ) -> None
Preamble	scope extension normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent an extension method.
Parameters
Returns
Raises	<empty>
See also	f_public, f_extension
Method	X_public.m_extension

Preamble	scope extension normative sections Contract, Derived from, Public classes, Public methods, See also
Contract	general Must represent an extension class. constructor Must be constructible.
Public classes	Y_core
Public methods	m_core
See also	X_public
Derived from	X_public, X_public.Y_extension
Class	X_extension

Nested classes in X_extension

Public Methods in class X_extension

Default module qualifier test_scope_mix ends here. No default module active.

Scope qualifier extension ends here. New current scope: public.

13.3. Scope: Core

Scope below this point is set to core.

Preamble	scope public normative sections Contract, Public classes, Public functions, See also
Contract	general Must represent a public module. Must reference public classes in See_also for testing. Must reference public functions in See_also for testing.
Public classes	X_public, X_extension, X_core
Public functions	f_public, f_extension, f_core
See also	X_public, f_public
Module	test_scope_mix

Classes and functions below this point implicitly belong to package/module test_scope_mix.

Signature	test_scope_mix.f_public( ) -> None
Preamble	scope public normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent a public function. Must reference public classes in See_also for testing.
Parameters
Returns
Raises	<empty>
See also	X_public
Function	f_public

Signature	test_scope_mix.f_extension( ) -> None
Preamble	scope extension normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent an extension function. Must reference public and extension classes in See_also for testing. Must reference public functions in See_also for testing.
Parameters
Returns
Raises	<empty>
See also	X_public, X_extension, f_public
Function	f_extension

Signature	test_scope_mix.f_core( ) -> None
Preamble	scope core normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent a core function. Must reference public, extension, and core classes in See_also for testing. Must reference public and extension functions in See_also for testing.
Parameters
Returns
Raises	<empty>
See also	X_public, X_extension, X_core, f_public, f_extension
Function	f_core

Preamble	scope public normative sections Contract, Public classes, Public methods
Contract	general Must represent a public class. constructor Must be constructible.
Public classes	Y_extension, Y_core
Public methods	m_extension, m_core
Class	X_public

Nested classes in X_public

Preamble	scope extension normative sections Contract
Contract	general Must be constructible. constructor
Class	X_public.Y_extension

Preamble	scope core normative sections Contract, See also
Contract	general Must be constructible. constructor
See also	X_public.Y_extension
Class	X_public.Y_core

Public Methods in class X_public

Signature	test_scope_mix.X_public.m_extension( ) -> None
Preamble	scope extension normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent an extension method.
Parameters
Returns
Raises	<empty>
See also	f_public, f_extension
Method	X_public.m_extension

Signature	test_scope_mix.X_public.m_core( ) -> None
Preamble	scope core normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent a core method.
Parameters
Returns
Raises	<empty>
See also	X_public.m_extension, X_public.Y_core, f_public, f_extension, f_core
Method	X_public.m_core

Preamble	scope extension normative sections Contract, Derived from, Public classes, Public methods, See also
Contract	general Must represent an extension class. constructor Must be constructible.
Public classes	Y_core
Public methods	m_core
See also	X_public
Derived from	X_public, X_public.Y_extension
Class	X_extension

Nested classes in X_extension

Preamble	scope core normative sections Contract, See also
Contract	general Must be constructible. constructor
See also	X_public.Y_extension, X_public.Y_core
Class	X_extension.Y_core

Public Methods in class X_extension

Signature	test_scope_mix.X_extension.m_core( ) -> None
Preamble	scope core normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent a core method.
Parameters
Returns
Raises	<empty>
See also	X_public.m_extension, X_public.m_core, X_extension.Y_core, f_public, f_extension, f_core
Method	X_extension.m_core

Preamble	scope core normative sections Contract, See also
Contract	general Must represent a core class. constructor Must be constructible.
See also	X_public.Y_extension, X_public.Y_core, X_extension.Y_core
Class	X_core

Default module qualifier test_scope_mix ends here. No default module active.

Scope qualifier core ends here. New current scope: public.