cminx.aggregator

This module interfaces with the generated CMake parser. The primary entrypoint is DocumentationAggregator, which subclasses cminx.parser.CMakeListener. This class listens to all relevent parser rules, generates cminx.documentation_types.DocumentationType objects that represent the parsed CMake, and aggregates them in a single list.

Author:: Branden Butler
License:: Apache 2.0

class cminx.aggregator.DefinitionCommand(documentation: AbstractCommandDefinitionDocumentation | None, should_document: bool = True)

A container for documentation of definition commands, used to update the parameter list when a cmake_parse_arguments() command is encountered.

A definition command is a command that defines another command, so the function() and macro() commands are definition commands. Instances of this dataclass are placed on the top of a stack when definition commands are encountered.

documentation: AbstractCommandDefinitionDocumentation | None: The documentation for the definition command. If None, this DefinitionCommand will be ignored when popped.

should_document: bool = True: Whether the contained documentation object should be updated if a cmake_parse_arguments() command is found. When false, this object is ignored.

class cminx.aggregator.DocumentationAggregator(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=('#', '*', '=', '-', '_', '~', '!', '&', '@', '^'))))

Processes all docstrings and their associated commands, aggregating them in a list. Uses the given Settings object to determine aggregation settings, and will document commands without doccomments if the associated settings are set.

The method used to generate the documentation object for a given command is chosen by searching for a method with the name "process_<command name>" with two arguments: ctx that is of type cminx.parser.CMakeParser.Command_invocationContext, and docstring that is of type string.

consumed: List[ParserRuleContext]: A list containing all of the contexts that have already been processed

definition_command_stack: List[DefinitionCommand]: A stack containing the current definition command that we are inside. A definition command is any command that defines a construct with both a beginning command and an ending command, with all commands within being considered part of the definition. Examples of definition commands include function(), macro(), and cpp_class().

documented: List[DocumentationType]: All current documented commands

documented_awaiting_function_def: DocumentationType | None: A variable containing a documented command such as cpp_member() that is awaiting its function/macro definition

documented_classes_stack: List[ClassDocumentation | None]: A stack containing the documented classes and inner classes as they are processed

enterCommand_invocation(ctx: Command_invocationContext) → None: Visitor for all other commands, used for locating position-dependent elements of documented commands, such as cpp_end_class() that pops the class stack, or a function or method definition for cpp_member().

enterDocumented_command(ctx: Documented_commandContext) → None

Main entrypoint into the documentation processor and aggregator. Called by ParseTreeWalker whenever encountering a documented command. Cleans the docstring and dispatches ctx to other functions for additional processing (process_{command}(), i.e. process_function())

Parameters:: ctx – Documented command context, constructed by the Antlr4 parser.
Raises:: NotImplementedError – If no processor can be found for the command that was documented.

process_add_test(ctx: Command_invocationContext, docstring: str) → None

Extracts information from a CTest add_test() command. Note: this is not the processor for the CMakeTest ct_add_test() command, but the processor for the vanilla CMake add_test() command.

Parameters:

ctx – Documented command context. Constructed by the Antlr4 parser.
docstring – Cleaned docstring.

process_cmake_parse_arguments(ctx: Command_invocationContext, docstring: str) → None

Determines whether a documented function or macro uses *args or *kwargs. Accesses the last element in the definition_command_stack to update the documentation’s has_kwargs field.

Parameters:

ctx – Documented command context. Constructed by the Antlr4 parser.
docstring – Cleaned docstring.

process_cpp_attr(ctx: Command_invocationContext, docstring: str) → None

Extracts the name and any default values from the documented cpp_attr command.

Parameters:

ctx – Documented command context. Constructed by the Antlr4 parser.
docstring – Cleaned docstring.

process_cpp_class(ctx: Command_invocationContext, docstring: str) → None

Extracts the name and the declared superclasses from the documented cpp_class command.

Parameters:

ctx – Documented command context. Constructed by the Antlr4 parser.
docstring – Cleaned docstring.

process_cpp_constructor(ctx: Command_invocationContext, docstring: str) → None: Alias for calling process_cpp_member() with is_constructor=True.

process_cpp_member(ctx: Command_invocationContext, docstring: str, is_constructor: bool = False) → None

Extracts the method name and declared parameter types from the documented cpp_member command.

Parameters:

ctx – Documented command context. Constructed by the Antlr4 parser.
docstring – Cleaned docstring.
is_constructor – Whether the member is a constructor, this parameter is reflected in the generated

MethodDocumentation.

process_ct_add_section(ctx: Command_invocationContext, docstring: str) → None

Extracts section name and declared parameters.

Parameters:

ctx – Documented command context. Constructed by the Antlr4 parser.
docstring – Cleaned docstring.

process_ct_add_test(ctx: Command_invocationContext, docstring: str) → None

Extracts test name and declared parameters.

Parameters:

ctx – Documented command context. Constructed by the Antlr4 parser.
docstring – Cleaned docstring.

process_function(ctx: Command_invocationContext, docstring: str) → None

Extracts function name and declared parameters.

Parameters:

ctx – Documented command context. Constructed by the Antlr4 parser.
docstring – Cleaned docstring.

process_generic_command(command_name: str, ctx: Command_invocationContext, docstring: str) → None

Extracts command invocation and arguments for a documented command that does not have a dedicated processor function.

Parameters:

command_name – The documented command’s name, such as add_library.
ctx – Documented command context. Constructed by the Antlr4 parser.
docstring – Cleaned docstring.

process_macro(ctx: Command_invocationContext, docstring: str) → None

Extracts macro name and declared parameters.

Parameters:

ctx – Documented command context. Constructed by the Antlr4 parser.
docstring – Cleaned docstring.

process_option(ctx: Command_invocationContext, docstring: str) → None

Extracts information from an option() command and creates an OptionDocumentation from it. It extracts the option name, the help text, and the default value if any.

Parameters:

ctx – Documented command context. Constructed by the Antlr4 parser.
docstring – Cleaned docstring.

process_set(ctx: Command_invocationContext, docstring: str) → None

Extracts variable name and values from the documented set command. Also determines the type of set command/variable: String, List, or Unset.

Parameters:

ctx – Documented command context. Constructed by the Antlr4 parser.
docstring – Cleaned docstring.

settings: Settings: Application settings used to determine what commands to document