module helpgen.default_conf

Short summary

module pyquickhelper.helpgen.default_conf

Default values for the Sphinx configuration.

source on GitHub

Functions

function

truncated documentation

_skip

To skip some functions, see Skipping members.

custom_setup

See Sphinx core events.

get_default_javascript

Returns the style of additional style sheets

get_default_stylesheet

Returns the style of additional style sheets.

get_epkg_dictionary

Returns default dictionary for extension epkg_role().

get_first_line

Expects to find a text file with a line, the function extracts and returns this line.

latex_preamble

Default latex preamble.

set_sphinx_variables

Defines variables for Sphinx.

Documentation

Default values for the Sphinx configuration.

source on GitHub

pyquickhelper.helpgen.default_conf._skip(app, what, name, obj, skip, options)[source][source]

To skip some functions, see Skipping members.

source on GitHub

pyquickhelper.helpgen.default_conf.custom_setup(app, author)[source][source]

See Sphinx core events.

source on GitHub

pyquickhelper.helpgen.default_conf.get_default_javascript()[source][source]

Returns the style of additional style sheets

Returns

list of files

source on GitHub

pyquickhelper.helpgen.default_conf.get_default_stylesheet()[source][source]

Returns the style of additional style sheets.

Returns

list of files

source on GitHub

pyquickhelper.helpgen.default_conf.get_epkg_dictionary()[source][source]

Returns default dictionary for extension epkg_role.

source on GitHub

pyquickhelper.helpgen.default_conf.get_first_line(filename)[source][source]

Expects to find a text file with a line, the function extracts and returns this line.

source on GitHub

pyquickhelper.helpgen.default_conf.latex_preamble()[source][source]

Default latex preamble.

source on GitHub

pyquickhelper.helpgen.default_conf.set_sphinx_variables(fileconf, module_name, author, year, theme, theme_path, ext_locals, add_extensions=None, bootswatch_theme='spacelab', bootswatch_navbar_links=None, description_latex='', use_mathjax=False, use_lunrsearch=False, enable_disabled_parts='enable_disabled_documented_pieces_of_code', sharepost='facebook-linkedin-twitter-20-body', custom_style=None, extlinks=None, github_user=None, github_repo=None, title=None, book=True, link_resolve=None, nblayout='classic', doc_version=None)[source][source]

Defines variables for Sphinx.

Parameters
  • fileconf – location of the configuration file

  • module_name – name of the module

  • author – author

  • year – year

  • theme – theme to use

  • theme_path – theme path (sets html_theme_path)

  • ext_locals – context (see locals)

  • add_extensions – additional extensions

  • bootswatch_theme – for example, spacelab, look at spacelab

  • bootswatch_navbar_links – see sphinx-bootstrap-theme

  • description_latex – description latex

  • use_mathjax – set up the documentation to use mathjax, see sphinx.ext.mathjax, default option is True

  • use_lunrsearch – suggest autocompletion in sphinx, see sphinxcontrib-lunrsearch

  • enable_disabled_partsremove_undesired_part_for_documentation

  • sharepost – add share button to share blog post on usual networks

  • custom_style – custom style sheet

  • extlinks – parameter extlinks, example: {'issue': ('https://github.com/sdpython/pyquickhelper/issues/%s', 'issue ')}

  • github_user – git(hub) user

  • github_repo – git(hub) project

  • title – if not None, use title instead of module_name as a title

  • book – the output is a book

  • link_resolve – url where the documentation is published, used for parameter linkcode_resolve

  • nblayout'classic' or 'table', specifies the layout for the notebook gallery

  • doc_version – if not None, overwrites the current version

If the parameter custom_style is not None, it will call app.add_css_file(custom_style) in the setup.

Simple configuration file for Sphinx

We assume a module is configurated using the same structure as pyquickhelper. The file conf.py could just contain:

# -*- coding: utf-8 -*-
import sys, os, datetime, re
import solar_theme
from pyquickhelper.helpgen.default_conf import set_sphinx_variables

sys.path.insert(0, os.path.abspath(os.path.join(os.path.split(__file__)[0])))
set_sphinx_variables(__file__, "pyquickhelper", "Xavier Dupré", 2014,
                     "solar_theme", solar_theme.theme_path, locals())

# custom settings
...

setup.py must contain a string such as __version__ = 3.4. Close to the setup, there must be a file version.txt. You overwrite a value by giving a variable another value after the fucntion is called.

Some parts of the code can be disabled before generating the documentation. Those parts are surrounded by:

# -- HELP BEGIN EXCLUDE --
import module
# -- HELP END EXCLUDE --

If enable_disabled_parts is set to a string, these sections will become:

# -- HELP BEGIN EXCLUDE --
if hasattr(sys, <enable_disabled_parts>) and sys.<enable_disabled_parts>:
    import module
# -- HELP END EXCLUDE --

Changed in version 1.9: Uses jupyter_sphinx>=0.2.

source on GitHub