cminx.rstwriter

This module and associated classes provide a pure-Python interface for generating reStructuredText. The generated text may be either consumed by another Python application or directly written to a file-like object. This module does not currently perform syntax validation, so it is up to the application developer to not generate invalid RST structures.

Author:: Branden Butler
License:: Apache 2.0

class cminx.rstwriter.Directive(name: str, indent: int = 0, *arguments: str, 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=('#', '*', '=', '-', '_', '~', '!', '&', '@', '^'))))

Use cminx.RSTWriter.directive() to construct. Represents an RST directive, such as toctree or an admonition. Does not verify that the directive or its arguments are valid.

build_heading() → DirectiveHeading

Build directive heading format (ex. ‘.. toctree::’) and return.

Returns:: Correctly formatted directive heading string.

format_arguments() → str

Format argument list into the correct argument string for use with directives.

Returns:: A string representing the directive arguments.

option(name: str, value: str = '') → None: Add an option, such as toctree’s maxdepth. Does not verify if valid option

to_text() → str

Return text representation of this document

Returns:: The completed RST document in string form.

class cminx.rstwriter.DirectiveHeading(title: str, indent: str, args: str)

Represents the unique heading for a Directive (.. :<name>:)

build_heading_string() → None: Builds the directive heading string and stores in heading_str

class cminx.rstwriter.DocTest(test_line: str, expected_output: str, indent: str = '')

Represents an RST DocTest

build_doctest_string() → None: Populates DocTest.doctest_string with the RST string corresponding to this DocTest

class cminx.rstwriter.Field(field_name: str, field_text: str, indent: str = '')

Represents an RST field, such as Author

build_field_string() → None: Populates Field.field_string with the RST string corresponding to this field

class cminx.rstwriter.Heading(title: str, header_char: str)

Represents a section heading

build_heading_string() → None: Populates Heading.heading_string with the RST string corresponding to this heading

class cminx.rstwriter.ListType(value)

Represents the different types of RST lists.

BULLETED = 1: A bulleted RST list.

ENUMERATED = 0: An enumerated RST list.

class cminx.rstwriter.Option(name: str, value: str, indent: str)

Represents a directive option, such as maxdepth

build_option_string() → None: Builds the option string and stores in option_string

class cminx.rstwriter.Paragraph(text: str, indent: str = '')

Represents an RST paragraph

build_text_string() → None: Populates Paragraph.text_string with the RST string corresponding to this paragraph

class cminx.rstwriter.RSTList(items: Tuple[str], list_type: ListType, indent: str = '')

Represents one of the two types of RST lists: Enumerated or Bulleted

build_list_string() → None

Populates RSTList.list_string with the RST string corresponding to this list.

Raises:: ValueError – When list_type is unknown.

class cminx.rstwriter.RSTWriter(title: str, section_level: int = 0, 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=('#', '*', '=', '-', '_', '~', '!', '&', '@', '^'))), indent: int = 0)

Base reStructuredText writer. Does not perform verification. This class presents an object-oriented and procedural API for generating reStructuredText documents. The document is held in an intermediate object-oriented representation until the text representation is requested either through to_text() or by calling str() on this object.

build_heading() → Heading

Adds overline and underline to RSTWriter.title (character is RSTWriter.header_char) and returns it

Returns:: A fully constructed Heading object.

bulleted_list(*items: str) → None

Add a bulleted list to the document tree.

Parameters:: items – varargs containing the desired list items.

clear() → None: Clear all document tree elements (besides required heading)

directive(name: str, *arguments: str) → Directive

Construct a directive and return it

Parameters:

name – Name of the directive being used, such as toctree or admonition.
arguments – Varargs to be used as the directive arguments, such as a topic title.

doctest(test_line: str, expected_output: str) → None

Adds a doctest segment to the document tree. A doctest segment appears as an interactive python session. The doctest Python module can then be used to scan for these segments and execute the test_line to ensure the output is the same.

Parameters:

test_line – Python code segment being used as the line to be tested.
expected_output – The exact string that is expected to be returned when test_line is evaluated.

enumerated_list(*items: str) → None

Add an enumerated list to the document tree; e.g.

Item 1
Item 2

Parameters:: items – varargs containing the desired list items.

field(field_name: str, field_text: str) → None

Add a field, such as Author or Version, to the document tree.

Parameters:

field_name – Name of the field being added, such as Author.
field_text – Value of the field, such as the author’s name.

heading_level_chars: List[str] = ['#', '*', '=', '-', '_', '~', '!', '&', '@', '^']: Characters to use as heading overline/underline, indexed by section_level

section(title: str) → RSTWriter

Constructs another RSTWriter and adds it to the document before returning it for use

Parameters:: title – The heading title to be used for the new subsection.

simple_table(tab: List[List[str]], column_headings: List[str] = ())

Add a simple table to the document tree. tab is a 2-dimensional list containing the table data. The first index is the row, the second is column. The first column may not contain multiple lines, all other columns may. column_headings is a list where each element is treated as a heading for that specific column, i.e. index 0 will be the heading for the leftmost column.

Parameters:: tab – A two-dimensional list representing table data. First index is row, second is column. Each row

must have the same number of columns.

Parameters:: column_headings – A single-dimensional list containing column headings, if required. Index zero is the

heading for the left-most column. List must be same length as number of columns.

Raises:: ValueError – If tab has inconsistent numbers of columns or column_headings length (if nonzero) does not

match number of columns in tab.

text(txt: str) → None

Add a paragraph to document tree.

Parameters:: txt – The content of the new paragraph.

to_text() → str

Return text representation of this document

Returns:: The completed RST document in string form.

write_to_file(file: str | IO) → None

Write text representation of this document to file. File may be a string (path will be opened in write mode) or a file-like object.

Parameters:: file – File to write to. May be a string representing a real filepath on the local filesystem (will be

overwritten), or a file-like object.

Raises:

ValueError – If file is nothing or empty string.
TypeError – If file is not str or object with ‘write()’ method

class cminx.rstwriter.SimpleTable(tab: List[List[str]], headings: List[str])

Represents an RST simple table.

build_table_string() → None: Populates SimpleTable.table_string with the RST string equivalent of this table

cminx.rstwriter.get_indents(num: int) → str

Get the string containing the necessary indent. The number of spaces in the returned string equals three times the input number, because directives require three spaces so the text lines up with the first letter of the directive name.

Returns:: A string containing the correct number of space characters, derived from the indent level.

cminx.rstwriter.interpreted_text(role: str, text: str) → str

This function generates an interpreted text RST element from the specified text and using the specified role. Interpreted text may appear almost anywhere regular text can so making it a method of RSTWriter would limit its functionality.

Parameters:

role – The role of the interpreted text
text – The literal text of the interpreted text

Returns:

The interpreted text element as a string