conf.py Examples

• http://sphinx-doc.org/latest/config.html?highlight=conf#conf

Introduction

The configuration directory must contain a file named conf.py . This file (containing Python code) is called the « build configuration file » and contains all configuration needed to customize Sphinx input and output behavior.

The configuration file is executed as Python code at build time (using execfile() , and with the current directory set to its containing directory), and therefore can execute arbitrarily complex code.

Sphinx then reads simple names from the file’s namespace as its configuration.

pypi Example

• http://packages.python.org/an_example_pypi_project/sphinx.html#conf-py

In your doc/source directory is now a python file called conf.py .

This is the file that controls the basics of how sphinx runs when you run a build. Here you can do this like:

• Change the version/release number by setting the version and release variables.

• Set the project name and author name.

• Setup a project logo.

• Set the default style to sphinx or default . Default is what the standard python docs use.

and much much more.

Browsing through this file will give you an understanding of the basics.

Exclude patterns

• exclude_patterns

Conf.py file for this project

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# http://www.sphinx-doc.org/en/master/config
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
import platform
from datetime import datetime
from zoneinfo import ZoneInfo

import sphinx
import sphinx_material

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
# sys.path.insert(0, os.path.abspath("./src"))


project = "Documentation formats"
html_title = project

author = f"DevOps people"
html_logo = "images/documentation.png"
html_favicon = "images/documentation.png"
release = "0.1.0"
now = datetime.now(tz=ZoneInfo("Europe/Paris"))
version = f"{now.year}-{now.month:02}-{now.day:02} {now.hour:02}H ({now.tzinfo})"
today = version

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.doctest",
    "sphinx.ext.extlinks",
    "sphinx.ext.intersphinx",
    "sphinx.ext.todo",
    "sphinx.ext.mathjax",
    "sphinx.ext.viewcode",
    "sphinx_copybutton",
]

# https://sphinx-design.readthedocs.io/en/furo-theme/get_started.html
extensions.append("sphinx_design")


# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
html_static_path = ["_static"]
html_show_sourcelink = True
html_sidebars = {
    "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
}
extensions.append("sphinx_material")
html_theme_path = sphinx_material.html_theme_path()
html_context = sphinx_material.get_html_context()
html_theme = "sphinx_material"

extensions.append("sphinx_design")

extensions.append("sphinx.ext.intersphinx")
intersphinx_mapping = {
    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
    "python": ("https://docs.python.org/", None),
    "tuto_python": ("https://gdevops.frama.io/python/tuto/", None),
    "tuto_doc": ("https://gdevops.frama.io/documentation/tuto", None),
    "doc_news": ("https://gdevops.frama.io/documentation/news", None),
    "tuto_css": ("https://gdevops.frama.io/web/tuto-css/", None),
    "tuto_django": ("https://gdevops.frama.io/django/tuto/", None),
    "blockdiag": ("http://blockdiag.com/en/", None),
    "tuto_sphinx": ("https://gdevops.frama.io/documentation/sphinx", None),
}
extensions.append("sphinx.ext.todo")
todo_include_todos = True


# material theme options (see theme.conf for more information)
# https://gitlab.com/bashtage/sphinx-material/blob/master/sphinx_material/sphinx_material/theme.conf
# Colors
# The theme color for mobile browsers. Hex color.
# theme_color = #3f51b5
# Primary colors:
# red, pink, purple, deep-purple, indigo, blue, light-blue, cyan,
# teal, green, light-green, lime, yellow, amber, orange, deep-orange,
# brown, grey, blue-grey, white
# Accent colors:
# red, pink, purple, deep-purple, indigo, blue, light-blue, cyan,
# teal, green, light-green, lime, yellow, amber, orange, deep-orange
# color_accent = blue
# color_primary = blue-grey

# material theme options (see theme.conf for more information)
html_theme_options = {
    "base_url": "https://gdevops.frama.io/documentation/formats",
    "repo_url": "https://framagit.org/gdevops/documentation/formats",
    "repo_name": project,
    "html_minify": False,
    "html_prettify": True,
    "css_minify": True,
    "globaltoc_depth": -1,
    "repo_type": "gitlab",
    "color_primary": "green",
    "color_accent": "cyan",
    "theme_color": "#2196f3",
    "nav_title": f"{project} ({today})",
    "master_doc": False,
    "nav_links": [
        {
            "href": "genindex",
            "internal": True,
            "title": "Index",
        },
        {
            "href": "https://gdevops.frama.io/documentation/linkertree",
            "internal": False,
            "title": "Liens documentation",
        },
        {
            "href": "https://gdevops.frama.io/web/linkertree/",
            "internal": False,
            "title": "Liens Web",
        },
        {
            "href": "https://linkertree.frama.io/pvergain/",
            "internal": False,
            "title": "Liens pvergain",
        },
    ],
    "heroes": {
        "index": "Documentation formats",
    },
    "table_classes": ["plain"],
}
# https://github.com/sphinx-contrib/yasfb
extensions.append("yasfb")
feed_base_url = html_theme_options["base_url"]
feed_author = "Scribe"
# https://sphinx-design.readthedocs.io/en/furo-theme/get_started.html
extensions.append("sphinx_design")
# https://sphinx-tags.readthedocs.io/en/latest/quickstart.html#installation
extensions.append("sphinx_tags")
tags_create_tags = True
# Whether to display tags using sphinx-design badges.
tags_create_badges = True

extlinks = {
    "duref": (
        "http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#%s",
        "rST %s",
    ),
    "durole": (
        "http://docutils.sourceforge.net/docs/ref/rst/roles.html#%s",
        "rST role %s",
    ),
    "dudir": (
        "http://docutils.sourceforge.net/docs/ref/rst/directives.html#%s",
        "rST directive %s",
    ),
    "graphvizattr": (
        "https://graphviz.org/docs/attrs/%s/",
        "%s attribute",
    ),
    "dutree": (
        "https://docutils.sourceforge.io/docs/ref/doctree.html#%s",
        "%s",
    ),
}

def setup(app):
    from sphinx.ext.autodoc import cut_lines
    from sphinx.util.docfields import GroupedField
    app.add_object_type('confval', 'confval',
                        objname='configuration value',
                        indextemplate='pair: %s; configuration value')

language = "fr"
html_last_updated_fmt = ""

todo_include_todos = True
# html_favicon = "images/favicon.ico"

html_use_index = True
html_domain_indices = True


rst_prolog = """
.. |sphinx| image:: /images/documentation.png
.. |yaml| image:: /images/yaml_avatar.png
.. |JsonSchema| image:: /images/json_schema_avatar.png
.. |eb| image:: /images/executable_book_avatar.png
.. |yed| image:: /images/yed_avatar.png
.. |vrt| image:: /images/vrt_avatar.png
.. |arsouilles| image:: /images/arsouilles_avatar.png
.. |FluxWeb| image:: /images/rss_avatar.webp
"""
copyright = f"2018-{now.year}, {author} Built with sphinx {sphinx.__version__} Python {platform.python_version()}"