stouputils.applications.automatic_docs.sphinx.conf_file module#

Generation of the docs/source/conf.py file Sphinx reads.

The file is produced as text rather than imported from a template, because a fair part of it is decided by the caller’s arguments: which forge hosts the sources, which theme renders them, and which pygments styles colour them.

python_literal(value: dict[str, Any]) → str[source]#

Render a mapping as a Python literal fit for the generated conf.py.

Parameters:

value (dict[str, Any]) – Mapping to render

Returns:

The literal, with JSON booleans translated back to Python ones

Return type:

str

Examples

>>> python_literal({"a": True, "b": False})
'{\n\t"a": True,\n\t"b": False\n}\n'
get_sphinx_conf_content(
project: str,
project_dir: str,
author: str,
current_version: str,
copyright: str,
html_logo: str,
html_favicon: str,
html_theme: str = 'breeze',
github_user: str = '',
github_repo: str = '',
version_list: list[str] | None = None,
skip_undocumented: bool = True,
repo_url: str = '',
repo_provider: str = 'github',
repo_branch: str = 'main',
source_prefix: str = '',
edit_link_path: str = '',
pygments_light_style: str = 'vscode-light-plus',
pygments_dark_style: str = 'vscode-dark-plus',
default_mode: str = 'dark',
autodoc_mock_imports: list[str] | None = None,
) → str[source]#

Get the content of the Sphinx configuration file.

Parameters:

  • project (str) – Name of the project

  • project_dir (str) – Path to the project directory

  • author (str) – Author of the project

  • current_version (str) – Current version

  • copyright (str) – Copyright information

  • html_logo (str) – URL to the logo

  • html_favicon (str) – URL to the favicon

  • html_theme (str) – Theme rendering the documentation. Defaults to “breeze”

  • github_user (str) – GitHub username

  • github_repo (str) – GitHub repository name

  • version_list (list[str] | None) – List of versions. Defaults to None

  • skip_undocumented (bool) – Whether to skip undocumented members. Defaults to True

  • repo_url (str) – Repository URL used for source links, ex: “https://gitlab.example.com/group/project”

  • repo_provider (str) – Which key of FORGES describes the repository URL. Defaults to “github”

  • repo_branch (str) – Branch the source links point at. Defaults to “main”

  • source_prefix (str) – Path from the repository root to the importable package’s parent, ex: “src/”

  • edit_link_path (str) – Where the Sphinx sources are tracked, enabling the “edit this page” link Leave it empty when those sources are generated, since editing them would be pointless.

  • pygments_light_style (str) – Pygments style used in light mode

  • pygments_dark_style (str) – Pygments style used in dark mode

  • default_mode (str) – Colour mode a first-time visitor gets: “auto”, “light” or “dark”

  • autodoc_mock_imports (list[str] | None) – Packages autodoc replaces with a stub instead of importing Only name packages the documented code never calls at import time, since a mock answers every attribute with another mock, which turns an ordinary decorator or metaclass into a failed import.

Returns:

Content of the Sphinx configuration file

Return type:

str