🎛️ Defaults¶

When the confirm.sphinx extension is added to the extensions, it applies the common Sphinx settings of all our documentations and you only have to set project.

The extension only sets values which aren’t defined in your conf.py or via sphinx-build -D. So whatever you set yourself always wins.

Most values depend on GitLab CI/CD variables. That way, a docs build in a pipeline automatically knows

its source links,
its release,
whether todos should be visible.

CI/CD variables¶

The defaults read these environment variables:

#
# 🤖 marvinCI variables.
#

mci_deploy_tagless = environ.get('MCI_DEPLOY_TAGLESS', '')         # todos

#
# 🦊 GitLab CI variables.
#
# Read some predefined GitLab CI variables to configure the source links, the release, and the
# conditional todo visibility.
#

ci_project_url     = environ.get('CI_PROJECT_URL')                  # source
ci_default_branch  = environ.get('CI_DEFAULT_BRANCH', 'main')       # source, todos
ci_commit_ref_slug = environ.get('CI_COMMIT_REF_SLUG', 'unknown')   # source, release, todos
ci_commit_tag      = environ.get('CI_COMMIT_TAG')                   # release, todos

Note

Running sphinx-build locally, outside of a pipeline, works fine. The release is unknown and the source links are missing, that’s all.

Settings¶

html_theme

Set to confirm-sphinx.

html_favicon

The confirm IT docs icon, loaded from https://assets.confirm.ch/icon-variants/sphinx.svg.

html_theme_options

When CI_PROJECT_URL is set, it adds Furo’s source_view_link and source_edit_link. They’re merged into your own html_theme_options, so your options and the source links work side by side. They point to docs/ in the GitLab project:

On a tag, they point to the default branch.
On a branch, they point to the current branch.

Without CI_PROJECT_URL, your options stay untouched.

html_title

Your project name, e.g. in the sidebar and the browser tab, instead of Sphinx’s <project> <release> documentation.

author

confirm IT

copyright

The current year and the author, e.g. 2026, confirm IT.

release

The tag name (CI_COMMIT_TAG), otherwise the branch slug (CI_COMMIT_REF_SLUG).

language

en

autodoc_typehints

description, so type hints show up in the parameter descriptions instead of the signature.

autosectionlabel_maxdepth

3, so only the page title and the first two section levels get a label. This avoids duplicate label warnings for common deeper headings like “Examples”.

extensions

See Extensions below.

todo_link_only

True, so the todo list only shows a link to the todo instead of its source path.

todo_include_todos

See Todo visibility below.

mermaid_init_config

Renders Mermaid labels as SVG text instead of HTML, so diagrams look the same everywhere (e.g. in exports).

{
    'startOnLoad': False,
    'htmlLabels': False,
    'flowchart': {'htmlLabels': False},
}

If you set your own mermaid_init_config, it replaces this one completely, so include 'startOnLoad': False.

Extensions¶

The confirm-sphinx extension always installs and enables these extensions:

#
# 🧩 Enabled default extensions.
#

EXTENSIONS = (
    'sphinx.ext.autodoc',           # Generate docs from Python docstrings
    'sphinx.ext.autosectionlabel',  # Reference sections by their title, e.g. :ref:`Extensions`
    'sphinx.ext.extlinks',          # Shorten external links via roles defined in extlinks
    'sphinx.ext.ifconfig',          # Include content based on config values
    'sphinx.ext.intersphinx',       # Link to other projects' documentation
    'sphinx.ext.napoleon',          # Support Google & NumPy style docstrings
    'sphinx.ext.todo',              # Support todo directives, hidden in releases
    'sphinxcontrib.mermaid',        # Render Mermaid diagrams via .. mermaid::
    'sphinx_paramlinks',            # Make parameters linkable, e.g. :paramref:`func.param`
)

Hint

sphinxcontrib-django is installed as well, but it’s not enabled. Add sphinxcontrib_django to extensions in Django projects to improve the autodoc output for models & co.

You don’t need to list the extensions above in your conf.py, but it doesn’t hurt either.

Todo visibility¶

Todos are meant for drafts, not for releases. That’s why todo_include_todos shows them only on work-in-progress builds:

Build	Todos
Tag	🙈 Hidden
Default branch with `MCI_DEPLOY_TAGLESS` set	🙈 Hidden
Any other branch	👀 Shown

The same rule marks the release in the sidebar with 🚧 on work-in-progress builds, unless you set release yourself.