configblock.docprinter module

Class to print documentation for the options defined by a configuration

This class can be used to print a summary of the options available in a ConfigBlock hierarchy for a user’s documentation.

class configblock.docprinter.DocPrinter(stream: ~typing.TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, indent_width: int = 4, detail: int = 0, only_active: bool = False, section_order: ~typing.Tuple[~configblock.visitorbase.Section, ...] = (<Section.Options: 1>, <Section.Subconfigs: 2>, <Section.SubconfigTypes: 3>))

Bases: VisitorBase

Simple printer

begin() → bool

Begin the output for the provided hierarchy

Returns:

Whether the hierarchy should be entered

Return type:

bool

begin_globals() → bool

Begin writing the globals

Returns:

Whether the block should be entered

Return type:

bool

begin_options() → bool

Begin writing the options

Returns:

Whether the options should be iterated over

Return type:

bool

begin_subcfg(key: str, subcfg: ConfigBlock) → bool

Begin writing a single subconfig

Note that this method should not handle further iteration into the subconfig

Returns:

Whether the subconfig should be entered

Return type:

bool

begin_subcfg_types() → bool

Begin writing the subconfig types section

Returns:

Whether to iterate over the subconfiguration factories

Return type:

bool

begin_subcfgs() → bool

Begin writing the subconfigs section

Returns:

Whether the subconfigs section should be iterated over

Return type:

bool

property detail: int

Do not print options with a higher detail level than this

end_options() → None

End writing the options on the current block

end_subcfg_types() → None

End the subconfig types section

end_subcfgs() → None

End writing the subconfigs section

visit_default_subcfg_type(factory: Callable[[], ConfigBlock] | None, already_output: bool) → None

Visit the default subconfig factory

Parameters:

• factory (Optional[ConfigBlockFactory]) – The default subconfig factory for the current block

• already_visited (bool) – Whether or not the information has been output in the current stack. This is to prevent infinite recursion where a block has itself as the default type

visit_globals() → None

Visit the top global block

visit_option(key: str, option: OptionData) → None

Visit a single option

visit_subcfg_type(key: str, factory: Callable[[], ConfigBlock], already_output: bool) → None

Visit a single subconfig type

Parameters:

• factory (Optional[ConfigBlockFactory]) – The factory to visit

• already_visited (bool) – Whether or not the information has been output in the current stack. This is to prevent infinite recursion where a block has itself as the default type

configblock.docprinter.get_short_doc(obj) → str

Get the short docstring from an object