Documentation Module

Utilities for generating documentation for Commands

author:

Doug Skrypa

cli_command_parser.documentation.render_script_rst(path: PathLike, top_only: Bool = True, fix_name: Bool = True, fix_name_func: NameFunc = None) → str

Load all Commands from the file with the given path, and generate a single RST string based on those Commands

cli_command_parser.documentation.render_command_rst(command: CommandCls, fix_name: Bool = True, fix_name_func: NameFunc = None) → str

Parameters:

• command – The Command to document

• fix_name – Whether the file name should be re-formatted from CamelCase / snake_case to separate Title Case words or not (default: True)

• fix_name_func – The function to call if fix_name is True instead of the default one.

Returns:

The help text for the given Command, formatted using RST

cli_command_parser.documentation.load_commands(path: PathLike, top_only: Bool = False, include_abc: Bool = False) → Commands

Load all of the commands from the file with the given path and return them as a dict of {name: Command}.

If an OSError or a subclass thereof is encountered while attempting to load the file (due to the path not existing, or a permission error, etc), it will be allowed to propagate. An ImportError may be raised by import_module() if the specified path cannot be imported.

Parameters:

• path – The path to a file containing one or more Command classes

• top_only – If True, then only top-level commands are returned (default: all)

• include_abc – Whether Command classes that extend abc.ABC should be included in results.

Returns:

Dict containing the Commands loaded from the given file

cli_command_parser.documentation.filtered_commands(obj_map: dict[str, Any], top_only: Bool = False, include_abc: Bool = False) → Commands

cli_command_parser.documentation.top_level_commands(commands: Commands) → Commands

Filter the given commands to only the ones that do not have a parent present in the provided dict of commands

cli_command_parser.documentation.import_module(path: PathLike)

Import the module / package from the given path

class cli_command_parser.documentation.RstWriter(output_dir: PathLike, *, dry_run: Bool = False, encoding: str = 'utf-8', newline: str = '\n', ext: str = '.rst', module_template: str = '{header}\n\n.. currentmodule:: {module}\n\n.. automodule:: {module}\n   :members:\n   :undoc-members:\n   :show-inheritance:\n', skip_modules: Strings = None)

Bases: object

A helper class for generating RST documentation for a Python package and/or scripts containing Commands.

Parameters:

• output_dir – Directory in which RST files should be written.

• dry_run – If True, log the actions that would be taken instead of taking them.

• encoding – The text encoding to use for output.

• newline – The newline character to use for output.

• ext – The file extension / suffix (including the leading .) to use for output.

• module_template – The format string to use when generating RST for Python modules.

• skip_modules – A collection of module names (using package.module notation) that should be skipped when documenting a Python package via document_package(). Supports fnmatch / glob wildcards.

document_script(path: Path, subdir: str = None, name: str = None, replacements: Mapping[str, str] = None, top_only: Bool = True, **kwargs) → str

Generate an RST file to document a Python script containing one or more Command classes.

Parameters:

• path – Path for a file containing one or more Command classes.

• subdir – If specified, write RST output for this script in this subdirectory, relative to the specified output_dir.

• name – Replacement name to use as the stem of the RST file name and as the title of the page. To replace the RST file name, but preserve default behavior for the page title, use fix_name=False with this param. The default page title is based on the name of the file that contains the Command, but can be overridden by providing a doc_name value when defining the Command.

• replacements – A mapping of simple string replacements to apply to the generated RST content before saving it. For each key=value pair, rst_str = rst_str.replace(key, value) will be performed.

• top_only – If True (the default), then only top-level commands in the given file will be documented, otherwise all commands will be documented. When True, subcommands of the discovered top-level commands will still be documented.

• kwargs – Additional keyword arguments to pass to render_script_rst()

Returns:

The stem of the file name that was used when saving the RST content for the given script.

document_scripts(paths: Iterable[Path], subdir: str = None, top_only: Bool = True, *, index_name: str = None, index_header: str = None, index_subdir: str = None, caption: str = None, **kwargs)

document_module(module: str, subdir: str = None)

Generate an RST file to document a Python module.

Parameters:

• module – The name of the module that should be documented, using package.module notation.

• subdir – If specified, write RST output for the specified module in this subdirectory, relative to the specified output_dir.

document_package(pkg_name: str, pkg_path: Path, subdir: str = None, *, name: str = None, header: str = None, index: Bool = True, empty: Bool = False, caption: str = None, max_depth: int = 4) → list[str]

Parameters:

• pkg_name – The name of the package to document

• pkg_path – The path to the package

• subdir – The output subdirectory for package contents

• name – The name to use for the index file

• header – Header text to use in the index (default is based on the package name)

• index – Whether the index file should be created

• empty – Whether an index file should be created if the package had no modules to document

• caption – A caption to use for the index

• max_depth – The maximum depth of the table of contents tree. Use -1 to allow unlimited depth.

Returns:

List of the names from the contents of the package

write_index(name: str, header: str, contents: Strings, *, content_subdir: str = None, subdir: str = None, caption: str = None, max_depth: int = 4, **kwargs)

Write an RST index file with a table of contents that references one or more other documents.

Parameters:

• name – The file name to use when saving this index.

• header – The name of the index document. Written as a header above the toctree directive.

• contents – The names of the documents to include in the table of contents for this index.

• content_subdir – The subdirectory that contains the RST files referenced by contents, if any / not included in the contents values already.

• subdir – The output subdirectory to use when writing this index, if any.

• caption – A caption to use for the index

• max_depth – The maximum depth of the table of contents tree. Use -1 to allow unlimited depth.

• kwargs – Additional keyword arguments to be included as :key: <value> options to the toctree directive.

write_rst(name: str, content: str, subdir: str = None)