ycleptic.src.makedoc module

The make-doc subcommand implementation

ycleptic.src.makedoc.make_doc(L: list[dict], topname: str, toptext: str, fp: TextIOWrapper, docname: str = '', doctext: str = '', docexample: dict = {}, rootdir: str = '', footer_style: str = 'paragraph')[source]

Makes a sphinx/rtd-style doctree from the base config file provided including a root node.

This is a recursive function that will create a directory structure based on the attributes and subattributes in the provided list L. It will create a main file with the name topname and write the documentation for the top-level attributes, as well as any subattributes or single-valued attributes.

Parameters:

  • L (list of dict) – List of attributes and subattributes to document.

  • topname (str) – The bare stem name of the current RST file (e.g. config_ref or attribute_1). Used only for toctree entry generation; the actual output path is derived from fp.

  • toptext (str) – The text to include at the top of the documentation file.

  • fp (io.TextIOWrapper) – Open file handle to write the documentation into.

  • docname (str) – Title string for the document. Optional; defaults to the topname in double backticks.

  • doctext (str) – Introductory text for the document. Optional; defaults to toptext.

  • docexample (dict) – Example to render as a YAML code block. Optional.

  • rootdir (str) – Absolute path to the Sphinx source directory. Used to compute RST cross-reference labels relative to the source root. Optional.

  • footer_style (str) – Style of the auto-generated footer. Optional; defaults to "paragraph".