cminx.documentation_types

This module contains a large assortment of dataclasses that represent each of the different types of documented commands that CMinx recognizes. Each dataclass also implements an abstract process() method to convert the dataclass representation into an RST representation using RSTWriter.

Author:

Branden Butler

License:

Apache 2.0

class cminx.documentation_types.AbstractCommandDefinitionDocumentation(name: str, doc: str, params: List[str], has_kwargs: bool = False)

Abstract dataclass that acts as the parent of FunctionDocumentation and MacroDocumentation.

has_kwargs: bool = False

Whether this command definition has keyword arguments.

params: List[str]

The list of parameters a command definition takes

class cminx.documentation_types.AttributeDocumentation(name: str, doc: str, parent_class: str, default_value: str)

This is a special documentation type that stores information on a class’s attributes. Its :method:`process` method takes a directive created by ClassDocumentation.

It translates the CMakePP attribute definition into a Sphinx py:attribute directive, with a value option if it has a default value.

default_value: str

The default value of this attribute, if it has one.

parent_class: str

The class that defines this attribute.

process(writer: Directive) → None

Processes the data stored in this documentation type, converting it to RST form by using the given RST writer.

Parameters:

writer – RSTWriter instance that the documentation will be added to.

class cminx.documentation_types.CTestDocumentation(name: str, doc: str, params: ~typing.List[str] = <factory>)

This dataclass holds documentation information for a vanilla CTest test. These tests are created with the “add_test()” command from regular CMake, and documenting such a call will create this type of documentation.

process(writer: RSTWriter) → None

Processes the data stored in this documentation type, converting it to RST form by using the given RST writer.

Parameters:

writer – RSTWriter instance that the documentation will be added to.

class cminx.documentation_types.ClassDocumentation(name: str, doc: str, superclasses: List[str], inner_classes: List[ClassDocumentation], constructors: List[MethodDocumentation], members: List[MethodDocumentation], attributes: List[AttributeDocumentation])

This is a documentation type that represents a CMakePP class definition. It holds information on all the class’s constructors, methods, and attributes via MethodDocumentation and AttributeDocumentation. It also contains string identifiers for its superclasses and inner classes.

This class translates the associated CMakePP class definition into a Sphinx py:class directive, then loops over all constructors, methods, and attributes and calls their :method:`process` method to add their information to the class directive.

attributes: List[AttributeDocumentation]

A list of attribute documentation objects describing the class’s attributes.

constructors: List[MethodDocumentation]

A list of method documentation objects describing the constructors this class has.

inner_classes: List[ClassDocumentation]

Any classes defined within this class.

members: List[MethodDocumentation]

A list of method documentation objects describing the class’s methods.

process(writer: RSTWriter) → None

Processes the data stored in this documentation type, converting it to RST form by using the given RST writer.

Parameters:

writer – RSTWriter instance that the documentation will be added to.

superclasses: List[str]

A list of any superclasses this class has, empty if none

class cminx.documentation_types.DanglingDoccomment(name: str, doc: str)

Represents a doccomment that is not attached to any other entity. This documentation type’s name is left unused, and the doc contains the cleaned text of the dangling doccomment.

process(writer: RSTWriter) → None

Processes the data stored in this documentation type, converting it to RST form by using the given RST writer.

Parameters:

writer – RSTWriter instance that the documentation will be added to.

class cminx.documentation_types.DocumentationType(name: str, doc: str)

This is the base class for all documentation types. It defines a single abstract process() method that is used to write the documentation RST to a given RSTWriter.

doc: str

The full doc comment, cleaned of # characters.

name: str

The name of the documentation type. For functions this is the function name, for variables this is the variable name, etc.

abstract process(writer: RSTWriter) → None

Processes the data stored in this documentation type, converting it to RST form by using the given RST writer.

Parameters:

writer – RSTWriter instance that the documentation will be added to.

class cminx.documentation_types.FunctionDocumentation(name: str, doc: str, params: List[str], has_kwargs: bool = False)

This class serves as the representation of a documented CMake function definition. It converts the function definition directly to a Sphinx function directive.

process(writer: RSTWriter) → None

Processes the data stored in this documentation type, converting it to RST form by using the given RST writer.

Parameters:

writer – RSTWriter instance that the documentation will be added to.

class cminx.documentation_types.GenericCommandDocumentation(name: str, doc: str, params: List[str])

This class represents any documented command that does not fit into any of the other documentation types.

All this class does is translate the documented command into a Sphinx function directive with a warning that it is a command invocation and not a definition.

params: List[str]

Any parameters passed to the command, unfiltered since this documentation type has no knowledge of the command

process(writer: RSTWriter) → None

Processes the data stored in this documentation type, converting it to RST form by using the given RST writer.

Parameters:

writer – RSTWriter instance that the documentation will be added to.

class cminx.documentation_types.MacroDocumentation(name: str, doc: str, params: List[str], has_kwargs: bool = False)

This class serves as the representation of a documented CMake macro definition. It converts the macro definition directly to a Sphinx function directive and adds a note directive specifying that it is a macro.

process(writer: RSTWriter) → None

Processes the data stored in this documentation type, converting it to RST form by using the given RST writer.

Parameters:

writer – RSTWriter instance that the documentation will be added to.

class cminx.documentation_types.MethodDocumentation(name: str, doc: str, parent_class: str, param_types: List[str], params: List[str], is_constructor: bool, is_macro: bool = False)

This is a special documentation type that holds information on a class’s method or constructor.

Its :method:`process` method requires a directive created by ClassDocumentation.

It translates the CMakePP method definition into a Sphinx py:method directive, with a note if it is a macro.

is_constructor: bool

Whether this method is a constructor.

is_macro: bool = False

Whether the linked command is a macro or a function. If true, a note saying so is generated.

param_types: List[str]

The types of the parameters to the method

params: List[str]

The parameter names.

parent_class: str

The class that this method is defined as a part of.

process(writer: Directive) → None

Processes the data stored in this documentation type, converting it to RST form by using the given RST writer.

Parameters:

writer – RSTWriter instance that the documentation will be added to.

class cminx.documentation_types.ModuleDocumentation(name: str, doc: str)

Represents documentation for an entire CMake module

process(writer: RSTWriter) → None

Processes the data stored in this documentation type, converting it to RST form by using the given RST writer.

Parameters:

writer – RSTWriter instance that the documentation will be added to.

class cminx.documentation_types.OptionDocumentation(name: str, doc: str, type: VarType | str, value: str | None, help_text: str)

This class documents a CMake option() command, representing a user-configurable option that can be selected via the cache. The RST form of this documentation also uses the data directive, but includes a note specifying the variable is an option.

help_text: str

The help text that the option has.

process(writer: RSTWriter) → None

Processes the data stored in this documentation type, converting it to RST form by using the given RST writer.

Parameters:

writer – RSTWriter instance that the documentation will be added to.

class cminx.documentation_types.SectionDocumentation(name: str, doc: str, expect_fail: bool, params: ~typing.List[str] = <factory>, is_macro: bool = False)

This class provides support for documenting CMakeTest test sections. It translates the section exactly as TestDocumentation except that the warning says that it is a test section.

process(writer: RSTWriter) → None

Processes the data stored in this documentation type, converting it to RST form by using the given RST writer.

Parameters:

writer – RSTWriter instance that the documentation will be added to.

class cminx.documentation_types.TestDocumentation(name: str, doc: str, expect_fail: bool, params: ~typing.List[str] = <factory>, is_macro: bool = False)

This class provides support for documenting CMakeTest tests. It translates the test definition into a Sphinx function definition with an EXPECTFAIL parameter if the test is expected to fail and a warning stating that it is a test and should not be called manually.

expect_fail: bool

Whether this test expects to fail.

is_macro: bool = False

Whether the linked command is a macro or a function. If true, a warning stating so is generated.

params: List[str]

Any parameters defined by the linked function.

process(writer: RSTWriter) → None

Processes the data stored in this documentation type, converting it to RST form by using the given RST writer.

Parameters:

writer – RSTWriter instance that the documentation will be added to.

class cminx.documentation_types.VarType(value)

The types of variables accepted by the CMake set() command

LIST = 2

A List variable, ex: set(list_var item1 item2 item3)

STRING = 1

A String variable, ex: set(str_var "Hello")

UNSET = 3

Unsetting a variable, i.e. not an actual variable but a declaration that a variable no longer exists. Ex: set(MyVar)

class cminx.documentation_types.VariableDocumentation(name: str, doc: str, type: VarType | str, value: str | None)

This class serves as the representation of a documented CMake variable definition (set() command). It can only recognize the CMake primitives str and list, as well as the implied unset() when no value is given.

This class translates the definition into a Sphinx data directive, with a Default value field and a type field.

process(writer: RSTWriter) → None

Processes the data stored in this documentation type, converting it to RST form by using the given RST writer.

Parameters:

writer – RSTWriter instance that the documentation will be added to.

type: VarType | str

The type that the variable is.

value: str | None

A default value that the variable has