Skip to content

Latest commit

 

History

History
152 lines (103 loc) · 5.5 KB

1b_doc_sphinx_howto.md

File metadata and controls

152 lines (103 loc) · 5.5 KB

Using Sphinx to write and build documentation

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

Index

Background

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:

How to build and view the documentation

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

How to write docstrings for Back In Time

Back In Time uses the Google style for docstrings. Please stick to this convention. Look into documentation of sphinx.ext.napoleon for extended examples.

How to add new modules to the documentation

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 the autodoc extension is able to find the files (navigate relative to the doc-dev folder).

  • Generate the initial .rst files for the new modules via sphinx-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) in doc-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")!

Commonly used rst markups in the docstring

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``
    

Known issues with documentation generation

  • 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 before make html

May 2024