localecmddoc.autodoc

Functions for creating automatic documentation of localecmd.Modules.

Module Contents

Functions

write_module_docs	Write the files with the Modules documentation to disk.
write_file	Write txt to file if the file does not contain this text already.
create_module_doc_output	Create a string of all docstrings within the module in markdown format.
fill_md_directive	Set up directive with given properties
getdoc_topic	Get docstring from Topic and translate it to markdown
getdoc_cmd	Get docstring from Function and translate it to markdown.
translate_parameters	Translate parameters and types in the parameters section of a doctring
remove_injected_argument	Remove any parameters for arguments that will be injected.
remove_python_code_blocks	Remove any markdown python code blocks.

API

write_module_docs(modules: Iterable[localecmd.Module], output_folder: pathlib.Path, file_extension: str = '.md', *, remove_pycode: bool = True)

Write the files with the Modules documentation to disk.

Attention

Use a dedicated output folder. The files within the output folder that do not belong to the docs will be deleted.

Parameters:

• modules (Iterable[Module]) – Modules to write the docs for.

• output_folder (pathlib.Path) – Into which folder to write the files. If not existing, this folder will be created.

• file_extension (str, optional) – File extension of output files. Default is ‘.md’

• remove_pycode (bool) – If Python code blocks should be removed from the output.

write_file(file: pathlib.Path, txt: str)

Write txt to file if the file does not contain this text already.

create_module_doc_output(module: localecmd.Module, *, remove_pycode: bool) → str

Create a string of all docstrings within the module in markdown format.

Parameters:

• module (Module) – The module to create the documentation for

• remove_pycode (bool) – If Python code blocks should be removed from the output.

fill_md_directive(directive: str, content: str, arg: str) → str

Set up directive with given properties

getdoc_topic(topic: localecmd.topic.Topic, directive: str) → str

Get docstring from Topic and translate it to markdown

getdoc_cmd(cmd: localecmd.Function, directive: str, *, remove_pycode: bool) → str

Get docstring from Function and translate it to markdown.

Parameters:

• cmd (Function) – Function containing the docstring

• directive (str) – Sphinx directive to use for the resulting documentation.

• remove_pycode (bool) – If Python code blocks should be removed from the output.

translate_parameters(s: str, fullname: str = '')

Translate parameters and types in the parameters section of a doctring

Docstring must be sphinx-style

Parameters:

• s (str) – docstring to translate

• fullname (str) – Full name of function. Used to call f_(). defaults to “”

Returns:

Translated docstring

Return type:

str

remove_injected_argument(s: str, remove_arg: str) → str

Remove any parameters for arguments that will be injected.

remove_python_code_blocks(s: str) → str

Remove any markdown python code blocks.

Fencing may be with triple backticks or colons.