Skip to content

Sphinx#

Sphinx is a popular documentation tool for Python projects.

Preview of Documentation built with Sphinx using the Furo theme in light mode

Preview of Documentation built with Sphinx using the Furo theme in dark mode

Configuration#

Sphinx is configured via a conf.py file.

docs/conf.py 
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = "Sample Project"
copyright = "2023, Fraunhofer IIS"
author = "mkj"

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = []

templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

# https://pradyunsg.me/furo/
html_theme = "furo"

html_static_path = ["_static"]
# html_logo = "_static/logo.png"

# -- Options for MyST parser -------------------------------------------------
# https://myst-parser.readthedocs.io/

extensions += ["myst_parser"]

myst_enable_extensions = [
    "attrs_block",  # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#block-attributes
    "attrs_inline",  # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#inline-attributes
    "colon_fence",  # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#markdown-figures
]

# -- Options for sphinx-autoapi ----------------------------------------------
# https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html

extensions += [
    "sphinx.ext.napoleon",  # required to parse google-style docstrings
    "sphinx.ext.autodoc",  # required to parse typehints
    "autoapi.extension",
]
autoapi_dirs = ["../src/sample_project"]

# https://sphinx-autoapi.readthedocs.io/en/latest/how_to.html#how-to-include-type-annotations-as-types-in-rendered-docstrings
autodoc_typehints = "description"

See Sphinx Configuration for a list of supported options.

Extensions#

myst_parser#

Documentation

MyST - Markedly Structured Text - Parser

A Sphinx and Docutils extension to parse MyST, a rich and extensible flavour of Markdown for authoring technical and scientific documentation.

This extension of CommonMark allows for integration of markup previously only available when using reStructuredText.