Generate this documentation

The documentation can be written using RST format or javadoc format. The documentation can generated by:

python setup.py build_sphinx

It requires the full sources from GitHub and not only the installed package which does not contains the documentation. It will go through the following steps:

  • it will copy all files found in src in folder _doc/sphinxdoc/source/[project_name]
  • it will generates a file .rst for each python file in _doc/sphinxdoc/source/[project_name]
  • it will run the generation of the documentation using Sphinx.
  • notebooks can be placed in _doc/notebooks, they will be added to the documentation
  • it will generated aggregated pages for blog posts added to _doc/sphinxdoc/source/blog/YYYY/<anything>.rst.

The results are stored in folder _doc/sphinxdoc/build. On Windows, the batch file build_setup_help_on_windows.bat copies all files into dist/html.

Configuration:

#-*- coding: utf-8 -*-
import sys
import os
import datetime
import re
import solar_theme

sys.path.insert(0, os.path.abspath(os.path.join(os.path.split(__file__)[0])))
from pyquickhelper.helpgen.default_conf import set_sphinx_variables
set_sphinx_variables(__file__, "pyquickhelper", "Xavier Dupré", 2016,
                     "solar_theme", solar_theme.theme_path, locals(),
                     extlinks=dict(issue=('https://github.com/sdpython/pyquickhelper/issues/%s', 'issue {0} on GitHub')))

# there is an issue with this attribute on Anaconda math_number_all
assert math_number_all or not math_number_all
blog_root = "http://www.xavierdupre.fr/app/pyquickhelper/helpsphinx/"

Design

The module is organized as follows:

  • pyquickhelper/src/pyquickhelper: contains the sources of the modules
  • pyquickhelper/_unittests/: contains the unit tests, they can run with program run_unittests.py
  • pyquickhelper/_unittests/_doc/notebooks: contains the notebooks included in the documentation
  • pyquickhelper/_unittests/_doc/sphinxdoc/source: contains the sphinx documentation
  • pyquickhelper/_unittests/_doc/sphinxdoc/blog/YYYY: contains the blog posts

When the documentation is being generated, the sources are copied into pyquickhelper/_unittests/_doc/sphinxdoc/source/pyquickhelper. The documentation can be in javadoc format is replaced by the RST syntax. Various files are automatically generated (indexes, examples, FAQ). Then sphinx is run. After the documentation is generated, everything is copied into folder pyquickhelper/dist.

python setup.py build_sphinx generates the documentation (see process_standard_options_for_setup).

Default configuration

  • Sphinx
  • coverage
  • Extension, see code of set_sphinx_variables <pyquickhelper.helpgen.default_conf.set_sphinx_variables>

As the documentation creates graphs to represent the dependencies, Graphviz needs to be installed. Here is the list of tools usually used:

If you need to use Antlr:

Notebooks

Notebooks in folder pyquickhelper/_doc/notebooks will be automatically converted into html, rst, pdf, slides formats but that requires latex and pandoc.