module helpgen.sphinx_main

Short summary

module pyquickhelper.helpgen.sphinx_main

Contains the main function to generate the documentation for a module designed the same way as this one, generate_help_sphinx().

source on GitHub

Functions

function	truncated documentation
_check_sphinx_configuration	Operates some verification on the configuration.
_import_conf_extract_parameter	Imports the configuration file and extracts some of the parameters it defines. Fills the following lists.
_process_sphinx_in_private_cmd
generate_help_sphinx	Runs the help generation:

Documentation

Contains the main function to generate the documentation for a module designed the same way as this one, generate_help_sphinx.

source on GitHub

pyquickhelper.helpgen.sphinx_main._check_sphinx_configuration(conf, fLOG)

Operates some verification on the configuration.

Parameters:

• conf – sphinx configuration

• fLOG – logging function

Returns:

list of gallery folders

source on GitHub

pyquickhelper.helpgen.sphinx_main._import_conf_extract_parameter(root, root_source, folds, build, newconf, all_tocs, build_paths, parameters, html_static_paths, fLOG)

Imports the configuration file and extracts some of the parameters it defines. Fills the following lists.

Parameters:

• root – folder of the package

• root_source – folder of the sources

• folds – folder of the documentation

• build – build path

• newconf – unused except in an error message

• all_tocs – list to fill

• build_paths – list to fill

• parameters – list to fill

• html_static_paths – list to fill

• fLOG – logging function

• all_tocs

• build_paths

• parameters

• html_static_paths

source on GitHub

pyquickhelper.helpgen.sphinx_main._process_sphinx_in_private_cmd(list_args, fLOG)

pyquickhelper.helpgen.sphinx_main.generate_help_sphinx(project_var_name, clean=False, root='.', filter_commit=<function <lambda>>, extra_ext=None, nbformats=('ipynb', 'slides', 'html', 'python', 'rst', 'pdf', 'github'), layout=None, module_name=None, from_repo=True, add_htmlhelp=False, copy_add_ext=None, direct_call=False, fLOG=<function fLOG>, parallel=1, extra_paths=None, fexclude=None)

Runs the help generation:

• copies every file in another folder,

• replaces comments in doxygen format into rst format,

• replaces local import by global import (tweaking sys.path too),

• calls sphinx to generate the documentation.

Parameters:

• project_var_name – project name

• clean – if True, cleans the previous documentation first (html files)

• root – see below

• filter_commit – function which accepts a commit to show on the documentation (based on the comment)

• extra_ext – list of file extensions to document (not .py)

• nbformats – requested formats for the notebooks conversion

• layout – list of formats sphinx should generate such as html, latex, pdf, docx, it is a list of tuple (layout, build directory, parameters to override), if None –> [("html", "build", {})]

• module_name – name of the module (must be the folder name src/module_name if None, module_name will be replaced by project_var_name

• from_repo – if True, assumes the sources come from a source repository, False otherwise

• add_htmlhelp – run HTML Help too (only on Windows)

• copy_add_ext – additional file extension to copy

• direct_call – direct call to sphinx with sphinx_build if True or run a command line in an another process to get a clear environment

• parallel – degree of parallelization

• extra_paths – extra paths when importing configuration

• fexclude – function which tells which file not to copy in the folder used to build the documentation

• fLOG – logging function

The result is stored in path: root/_doc/sphinxdoc/source. We assume the file root/_doc/sphinxdoc/source/conf.py exists as well as root/_doc/sphinxdoc/source/index.rst.

If you generate latex/pdf files, you should add variables latex_path and pandoc_path in your file conf.py which defines the help.

You can exclud some part while generating the documentation by adding:

• # -- HELP BEGIN EXCLUDE --

• # -- HELP END EXCLUDE --

latex_path  = r"C:/Program Files/MiKTeX 2.9/miktex/bin/x64"
pandoc_path = r"%USERPROFILE%/AppData/Local/Pandoc"

Run help generation

# from the main folder which contains folder src or the sources
generate_help_sphinx("pyquickhelper")

By default, the function only consider files end by .py and .rst but you could add other files sharing the same extensions by adding this one in the extra_ext list.

The function requires:

• pandoc

• latex

Warning

Some themes such as Bootstrap Sphinx Theme

do not work on Internet Explorer. In that case, the file <python_path>/Lib/site-packages/sphinx/themes/basic/layout.html must be modified to add the following line (just below Content-Type).

<meta http-equiv="X-UA-Compatible" content="IE=edge" />

The code should follow as much as possible the sytle convention PEP8. The module autopep8 can modify a file or all files contained in one folder by running the following command line:

autopep8 <folder> --recursive --in-place --pep8-passes 2000 --verbose

About encoding: utf-8 without BOM is the recommanded option.

About languages: only one language can be specificied even if you have

multiple configuration file. Only the language specified in the main conf.py will be considered.

About blog posts: the function uses sphinx directives blogpost and blogpostagg to create

a simple blog aggregator. Blog posts will be aggregated by months and categories. Link to others parts to the documentation are possible. The function also create a file rss.xml which contains the ten last added blog post. This file contains an absolute link to the blog posts. However, because the documentation can be published anywhere, the string __BLOG_ROOT__ was inserted instead of the absolute url to the website. It must be replaced before uploaded or the parameter blog_root can be specified in the configuration file conf.py.

Warning

Parameter add_htmlhelp calls Html Help WorkShop. It also changes the encoding of the HTMLoutput into cp1552 (encoding for Windows) instead of utf-8.

Warning

An issue was raised on Linux due to the use of .. only:: html (AttributeError: Can't pickle local object 'setup.<locals>.<lambda>'). It disappeared when using only one thread and not 2 as it was previously. Parameter parallel was introduced to make that change and the default value is not 1.

Others necessary tools:

SVG included in a notebook (or any RST file) requires Inkscape to be converted into Latex.

How to dd an extra layer to the documentation?

The following commit on project python3_module_template shows which changes needs to be done to add an extra layer of for the documentation.

The function assumes IPython 3 is installed. It might no work for earlier versions (notebooks). Parameters from_repo, use_run_cmd were added. Notebook conversion to slides is implemented, install reveal.js if not installed. Parameter add_htmlhelp was added. It runs HtmlHelp on Windows

"C:\Program Files (x86)\HTML Help Workshop\hhc.exe" build\htmlhelp\<module>.hhp

The documentation includes blog (with sphinx command .. blogpost:: and python scripts .. runpython::. The second command runs a python script which outputs RST documntation adds it to the current documentation. The function automatically adds custom role and custom directive sharenet. The function directly calls sphinx, nbconvert. When there are too many notebooks, the notebook index is difficult to read. It does not require to get script location. Not enough stable from virtual environment.

Set BOKEH_DOCS_MISSING_API_KEY_OK to 1. bokeh sphinx extension requires that or a key for the google API (???). The function was updated to use Sphinx 1.6.2. However, you should read blog post Bug in Sphinx 1.6.2 for custom css if you have any trouble with custom css. Add a report in all_notebooks.rst about notebook coverage. Parameter parallel was added. The parameter nblayout in the configuration file specifies the layout for the notebook gallery. 'classic' or 'table'. The parameter nbneg_pattern can be used to remove notebooks from the gallery if they match this regular expression. It automatically adds video and image directives. remove_unicode can set to False or True in the documentation configuration file to allow or remove unicode characters before compiling the latex output. Import conf.py in a separate process before running the generation of the documentation. Do not import it directly.

source on GitHub