About conf.py for sphinx

Documentation on the configuration file

The conf.py file is called the “build configuration file” and contains all configuration needed to customize Sphinx input and output behavior.

Path Setup

Setting up the sys.path for all the directories to document. If extensions or modules are present in another directory, then need to add those directories to sys.path. If the directory is relative to the documentation's root directory, use os.path.abspath to make it absolute.

import os
import pathlib
import shutil
import sys

import weldx

sys.path.insert(0, os.path.abspath(""))

Project Information

project: The documented project’s name must be specified.

author: The author name of the document. The default value is ‘unknown’.

copyright: A copyright statement in the style ‘2020, Author Name’.

version: The major project version, used as the replacement for |version|. For example, for the python documentation, this may be like 3.6.

release: The full project version, used as the replacement for |release|. For example, for the Python documentation, this may be something like 3.6.0rc1. If you don’t need the separation provided between version and release, just set them both to the same value.

pygments_style: The style name to use for Pygments highlighting of source code. The default style is selected by the theme for HTML output, and 'sphinx' otherwise.

project = "weldx"
copyright = "2020, BAM"
author = "BAM"

# The full version, including alpha/beta/rc tags
release = weldx.__version__

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = "sphinx"

General configuration

extensions:

Adding any Sphinx extension module names as strings. Most of the extensions starting with sphinx (named ‘sphinx.ext.*’) or custom extensions.

extensions = [
    "recommonmark",
    "sphinxcontrib.napoleon",
    "nbsphinx",
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "sphinx.ext.mathjax",
    "sphinxcontrib.bibtex",
    "sphinx_copybutton",
    "sphinx_asdf",
    "numpydoc",
]

• recommonmark – To configure the sphinx project for Markdown support, for parsing the CommonMark Markdown flavor.

• sphinxcontrib.napoleon – Support for the Numpy and Google-style docstrings.

• sphinx.ext.autodoc – To import the modules to be documented and pull in documentation for docstrings in a semi-automatic way.

• nbsphinx – The extension that provides a source parser for *.ipynb (Jupyter Notebook) files.

• sphinx.ext.autosummary – The extension generates function/method/attribute summary lists, similar to those output e.g. by Epydoc and other API doc generation tools.

• sphinx.ext.mathjax – Math support in sphinx.

• sphinxcontrib.bibtex – This extension allows BibTex style citations to be inserted into documentation generated by Sphinx, through a bibliography directive.

• sphinx_copybutton - A small sphinx extension to add a “copy” button to code blocks.

• sphinx_asdf – Plugin for sphinx that enables generation of documentation from ASDF schemas.

• numpydoc – The extension for handling docstrings formatted according to the Numpy documentation format.

source_suffix:

The file extensions of source files. Sphinx considers the files with the below suffix as sources.

source_suffix = {
    ".rst": "restructuredtext",
    ".md": "markdown",
}

master_doc:

The document name of the “master” document, that is, the document that contains the root toctree directive. Default is contents.

# The master toctree document.
master_doc = "index"

exclude_patterns:

A list of glob-style patterns that should be excluded when looking for source files. They are matched against the source file names relative to the source directory, using slashes as directory separators on all platforms.

# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ["**.ipynb_checkpoints"]

templates_path:

A list of paths that contain extra templates (or templates that overwrite builtin/theme-specific templates). Relative paths are taken as relative to the configuration directory.

# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]

autosummary_feature:

.. autosummary::

The autosummary directive is for generating summary listings that contain links to the documented items, and short summary blurbs extracted from their docstrings. The autosummary directive can also optionally serve as a toctree entry for the included items.

autosummary_generate

Boolean indicating whether to scan all found documents for autosummary directives and to generate stub pages for each. It is disabled by default. It can also be a list of documents for which stub pages should be generated.

The new files will be placed in the directories specified in the :toctree: options of the directives.

The script sphinx-autogen or the new autosummary_generate config value is used to generate short “stub” files for the entries listed in the autosummary directives. The stub.rst files for items can be automatically generated when autosummary_generate is TRUE.

autosummary_generate = True

Options

• If we need the autosummary table to also serve as a toctree entry, use the toctree option, for example:

.. autosummary::
   :toctree: DIRNAME

The toctree option also signals to the sphinx-autogen script that stub pages should be generated for the entries listed in this directive. The option accepts a directory name as an argument, sphinx-autogen will by default place its output in this directory. If no argument is given, the output is placed in the same directory as the file that contains the directive. We can also use the caption option to give a caption to the toctree.

• When we don’t want the autosummary to show function signatures in the listing, include the nosignatures option:

.. autosummary::
   :nosignatures:

• We can specify a custom template with the template option. For example,

.. autosummary::
   :template: mytemplate.rst

Need to use the template mytemplate.rst in the templates_path to generate the pages for all entries listed.

• We can specify the recursive option to generate documents for modules and sub-packages recursively. For example,

.. autosummary::
   :recursive:

customizing templates

We can customize the stub page templates, in a similar way as the HTML Jinja templates.

Autosummary uses the following custom template files:

• autosummary/base.rst – fallback template

• autosummary/module.rst – template for modules

• autosummary/class.rst – template for classes

• autosummary/function.rst – template for functions

• autosummary/attribute.rst – template for class attributes

• autosummary/method.rst – template for class methods

numpydoc:

Numpydoc sphinx config options documentation to be added: • numpydoc_use_plots: bool Whether to produce plot:: directives for examples sections that contain import matplotlib or from matplotlib import.

• numpydoc_show_class_members: bool Whether to show all members of a class in the Methods and Attributes sections automatically. True by default.

• numpydoc_show_inherited_class_members: bool Whether to show all inherited members of a class in the Methods and Attributes sections automatically. If it’s false, inherited members won’t show. True by default.

• numpydoc_class_members_toctree: bool Whether to create a Sphinx table of contents for the lists of class methods and attributes. If a table of contents is made, Sphinx expects each entry to have a separate page. True by default.

• numpydoc_citation_re: str A regular expression matching citation which should be mangled to avoid conflicts due to duplication across the documentation.

• numpydoc_attributes_as_param_list: bool Whether to format the Attributes section of a class page in the same way as the Parameter section. If it’s False, the Attributes section will be formatted as the Methods section using an autosummary table. True by default.

• numpydoc_xref_param_type: bool Whether to create cross-references for the parameter types in the Parameters, Other Parameters, Returns and Yields sections of the docstring. False by default.

• numpydoc_xref_aliases : dict Mappings to fully qualified paths (or correct ReST references) for the aliases/shortcuts used when specifying the types of parameters. The keys should not have any spaces. Together with the intersphinx extension, you can map to links in any documentation.

• numpydoc_xref_ignore : set Words not to cross-reference. Most likely, these are common words used in parameter type descriptions that may be confused for classes of the same name. For example: numpydoc_xref_ignore = {'type', 'optional', 'default'}

Explicitly dis-/enabling Notebook Execution:

The notebook is not executed by default because it contains some execution_count values and it’s therefore not considered to be “without outputs”. Hence need to enable the feature by setting the option nbsphinx_execute = “always”

Explicitly we can also disable the feature option in the conf.py by setting nbsphinx_execute = “never” if we want to include a notebook without outputs but still need the “nbsphinx” to execute it.

Configuring the Kernels Kernel name: If we have multiple kernels installed, then we can choose to override the kernel saved in the notebook using nbsphinx_kernel_name options.

Kernel arguments: We can pass options to the kernel by setting nbsphinx_execute_arguments in conf.py to set plot options and output formats.

nbsphinx_execute = "always"
nbsphinx_execute_arguments = [
    "--InlineBackend.figure_formats={'svg', 'pdf'}",
    "--InlineBackend.rc={'figure.dpi': 96}",
]

nbsphinx_kernel_name = "python3"

sphinx-asdf:

It is a plugin for sphinx that enables the generation of documentation from ASDF schemas. The sphinx-asdf plugin provides two sphinx directives- asdf-autoschemas and asdf-schema.

The plugin also provides several configuration variables: • asdf_schema_path • asdf_schema_standard_prefix • asdf_schema_reference_mappings

# This variable indicates the top-level directory containing schemas.
# The path is relative to the location of conf.py in the package
asdf_schema_path = "../weldx/asdf/schemas"

# This variable indicates the standard prefix that is common to all schemas
# provided by the package.
asdf_schema_standard_prefix = "weldx.bam.de/weldx"

Schema references to other schemas in the same package are automatically converted to links in the generated documentation. (This assumes that all the references correspond to schemas that are explicitly generated by an asdf-schema directive). However, sometimes it is necessary to resolve references to schemas in other packages. The asdf_schema_reference_mapping configuration variable is provided for this purpose. It enables a mapping between references that begin with a particular prefix to a URL indicating another package's documentation. For example, to enable references to the ASDF Standard documentation to be resolved as links, include the following in your docs/conf.py file:

# enable references to the ASDF Standard documentation
asdf_schema_reference_mappings = [
    (
      "tag:stsci.edu:asdf",
      "http://asdf-standard.readthedocs.io/en/latest/generated/stsci.edu/asdf/",
    ),
]

nitpicky:

If true, Sphinx will warn about all references where the target cannot be found. Default is False. You can activate this mode temporarily using the -n command-line switch.

nitpick_ignore:

A list of (type, target) tuples (by default empty) that should be ignored when generating warnings in “nitpicky mode”. Note that type should include the domain name if present. Example entries would be ('py:func', 'int') or ('envvar', 'LD_LIBRARY_PATH').

Options for HTML output:

html_theme:

The “theme” that the HTML output should use. The default is 'default'.

html_theme = "pydata_sphinx_theme"

html_theme_path:

A list of paths that contain custom themes, either as subdirectories or as zip files. Relative paths are taken as relative to the configuration directory.

Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the built-in static files,
# so a file named "default.css" will overwrite the built-in "default.css".
html_static_path = ["_static"]

html_theme_options:

A dictionary of options that influence the look and feel of the selected theme. These are theme specific. For the options understood by the builtin themes.

html_theme_options = {
    "external_links": [{"url": "https://asdf.readthedocs.io/", "name": "ASDF Docs"}],
    "github_url": "https://github.com/BAMWelDX/weldx",
    "twitter_url": "https://twitter.com/BAMweldx",
    "use_edit_page_button": False,
}

html_logo:

If given, this must be the name of an image file (path relative to the configuration directory) that is the logo of the docs. It is placed at the top of the sidebar; its width should therefore not exceed 200 pixels. Default: None. The image file will be copied to the _static directory of the output HTML, but only if the file does not already exist there.

# enable references to the ASDF Standard documentation
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = "_static/WelDX_notext.svg"
html_favicon = "_static/WelDX_notext.ico"

html_context:

A dictionary of values to pass into the template engine’s context for all pages. Single values can also be put in this dictionary using the -A command-line option of sphinx-build.

html_context = {
    "github_user": "BAMWelDX",
    "github_repo": "weldx",
    "github_version": "master",
    "doc_path": "doc",
}