cminx.documenter

This file contains the Documenter class, which is the top-level entrypoint into the CMinx documentation system. It handles parsing, aggregating, and RST writing.

Author:

Branden Butler

License:

Apache 2.0

class cminx.documenter.Documenter(file: str, title: str | None = None, module_name: str | None = None, settings: Settings = Settings(input=InputSettings(include_undocumented_function=True, include_undocumented_macro=True, include_undocumented_cpp_class=True, include_undocumented_cpp_attr=True, include_undocumented_cpp_constructor=True, include_undocumented_cpp_member=True, include_undocumented_ct_add_test=True, include_undocumented_ct_add_section=True, include_undocumented_add_test=True, include_undocumented_option=True, auto_exclude_directories_without_cmake=True, kwargs_doc_trigger_string=':param **kwargs:', exclude_filters=(), function_parameter_name_strip_regex='', macro_parameter_name_strip_regex='', member_parameter_name_strip_regex='', recursive=False, follow_symlinks=False), output=OutputSettings(directory=None, relative_to_config=False), logging=LoggingSettings(logger_config={}), rst=RSTSettings(file_extensions_in_titles=False, file_extensions_in_modules=False, prefix=None, module_path_separator='.', headers=('#', '*', '=', '-', '_', '~', '!', '&', '@', '^'))))

Generates RST documentation from aggregated documentation, combining DocumentationAggregator and RSTWriter. The entrypoint for this class is the process() method.

aggregator: DocumentationAggregator

The aggregator used to listen for parser rules and generate documentation objects.

input_stream: InputStream

The string stream used to read the CMake file.

lexer: CMakeLexer

The lexer used to generate the token stream.

module: Directive

The .. module:: directive that defines the module’s name.

module_name: str

The name of the CMake module, used as a default when no name given via a module doccomment.

parser: CMakeParser

The parser used to parse the token stream and call our listener. By default, an instance of ParserErrorListener is added.

process() → RSTWriter

Process cminx.aggregator.DocumentationAggregator.documented and build RST document from it.

Returns:

Completed RSTWriter document, also located in Documenter.writer

process_docs(docs: List[DocumentationType]) → None

Loops over document and calls cminx.documentation_types.DocumentationType.process() with writer.

Parameters:

docs – List of documentation objects.

settings: Settings

Settings used for aggregation and RST generation, passed down to all downstream components.

stream: TokenStream

The stream of tokens from the lexer, should be passed to the parser.

walker: ParseTreeWalker

Walks the parser tree at a given parser rule, used to kick off aggregation.

writer: RSTWriter

The writer that is passed to the aggregated documentation objects.