Feel free to open issues or contact the maintenance team on the mailing list if this text is difficult to understand or not helpful.
This file describes briefly how to
- build and view the source code "API" documentation of Back In Time "common" (CLI)
- add new modules to the documentation
- write docstrings
- known issues with documentation generation
- Background
- How to build and view the documentation
- How to write docstrings for Back In Time
- How to add new modules to the documentation
- Commonly used rst markups in the docstring
- Known issues with documentation generation
The documentation is generated automatically from the docstrings in the python source code files using Sphinx in combination with the following Sphinx-Extensions:
- autodoc to automatically generate rst doc files from the python docstrings.
- napoleon
to convert google-style docstrings to reStructuredText
rst
format required for autodoc. - viewcode to create links to browse the highlighted source code.
Further readings:
Open a terminal, navigate to the folder common/doc-dev
and call
make html # to generate the HTML documentation
make htmlOpen # to open the browser showing the generated HTML pages
Back In Time uses the Google style for
docstrings.
Please stick to this convention. Look into documentation of
sphinx.ext.napoleon
for extended examples.
There are two scenarios:
Scenario A: New module files are in a separate folder (not yet included in the doc generation so far)
-
Add the python source code folder to the file
doc-dev/conf.py
which is the configuration. Then theautodoc
extension is able to find the files (navigate relative to thedoc-dev
folder). -
Generate the initial
.rst
files for the new modules viasphinx-apidoc
, eg.sphinx-apidoc -o ./plugins ../plugins
This example will create a sub folder
doc-dev/plugins
with the.rst
files (one for each source file) indoc-dev/../plugins
. -
Add the new modules in the sub folder to the top-most root
index.rst
:# under "modules.rst" add this line add a link to new modules plugins/modules.rst
Scenario B: The new module files are in a folder that already contains other modules contained in the doc
To create the initial version of .rst
files for new modules eg. in the common
folder use
sphinx-apidoc -o . ..
TODO: How to remove old rst files with non-existing python files (eg. due to renaming or deletion)? Probably the -f ("force") argument could do this. Try it with -d ("dry-run")!
Despite using the Google docstring style rst markups can and should still be used to format text and cross-reference code.
-
Reference a class (with namespace if not in the same):
:py:class:`pluginmanager.PluginManager`
Important: Don't forget to surround the function name with back ticks otherwise Sphinx will not create a cross reference silently!
-
Reference a method/function:
:py:func:`takeSnapshot`
-
Reference a module:
:py:module:`datetime`
-
Specify the python type of an method/function argument:
Add the type name (with namespace if not in the same) in parentheses
"""Short description... Long description... Args: cfg (config.Config): Current configuration """
-
To indicate verbatim text (inline code) enclose it with two backticks each.
``True`` ``None`` ``de_DE.UTF-8``
-
Elements of PyQt can not be referenced. It is a known Issue without an acceptable solution. Name them via verbatime text (two backticks) only.
-
Sphinx'
make html
does not recreate the html file of a sub class if only the parent class docstring was changed.Impact: Inherited documentation in the sub class is not up to date
Work around: Use
make clean
beforemake html
May 2024