Small Python script to convert Python Google-Style docstrings to quarto files to be used to render a Python package documentation using a quarto website. This script started as the author was not happy with existing software to document Python packages, namely sphinx altough having a variety of features.
As sphinx has been used previously, this parser partially relies on the sphinx syntax for cross-referencing classes, functions, and methods.
Uses the Python standard libraries importlib to import all visible classes
and functions of an existing package and inspect to inspect these objects.
The Python package
docstring_parser is used to
parse Google style docstrings which are then converted into quarto .qmd
files.
In the simplest case:
python3 makedocs.py <action> -p <package>
... where <action> can be init or document. init will initialize a new
project and stores all necessary files in a directory _quarto. If initialized
once, an error will be thrown if executed again to avoid overwriting changes
made by the user. The argument --overwrite can be used to force-overwrite
the existing quarto files as well as _quarto.yml. document will only update
the man pages created from the Python docstrings as well as update the
'Function references' and 'Class references' section in the _quarto.yml file.
Additional options are available to change a few things. For more details see:
python3 makedocs.py --help
Based on the syntax of sphinx, cross-referencing in the docstrings is done
via :py:class:, :py:func: and :py:meth: followed by the name/path of the
class, function, or method.
:py:class:\package.module.class`` references a class:py:class:\class <package.module.class>`references a class but will only displayclass` (custom text) in the rendered quarto document.:py:class\class`` expects the class to be in the same module as the class it is references from.
Similarely functions can be cross-referenced with the same system:
:py:func:\package.module.function`` references a func:py:func:\function <package.module.function>`references a func but will only displayfunction` (custom text) in the rendered quarto document.:py:func\function`` expects the func to be in the same module as the func it is references from.
Last but not least, sibling methods can be referenced within a class using:
:py:meth:\method``
The script does not validate if these references are valid, but will link to them
in the quarto documents. quarto render will throw warnings if links cannot be
resolved.
One additional feature is a special comment in the Example section of each
Google style docstring. Whenver a line (code line) starts with #:, the example
will be split at this point, resulting in multiple quarto code chunks allowing
for 'in-line' (in-between chunks) output in the exercises. A line solely containing
#: also initiales a new code chunk but will not be shown (hidden chunk splitter).
As an example, this could look as follows in the docstring:
Example:
>>> # Basic addition
>>> a = 10 + 3
>>> a
>>> #: Basic subtraction
>>> 20 - 4
>>> #:
>>> 20 - 5