stouputils.applications.automatic_docs.sphinx.builder module#

Orchestration of a documentation build: lay out the folders, write the generated files, then run Sphinx.

sphinx_docs is the only entry point most projects ever call. Every step it performs is a parameter, so a project needing a different landing page or a different build command replaces that one callable instead of forking the whole routine.

generate_documentation(
source_dir: str,
modules_dir: str,
project_dir: str,
build_dir: str,
) → None[source]#

Generate documentation using Sphinx.

Parameters:

  • source_dir (str) – Source directory

  • modules_dir (str) – Modules directory

  • project_dir (str) – Project directory

  • build_dir (str) – Build directory

sphinx_docs(root_path: str, project: str, project_dir: str = '', author: str = 'Author', copyright: str = '2025, Author', html_logo: str = '', html_favicon: str = '', html_theme: str = 'breeze', github_user: str = '', github_repo: str = '', repo_url: str = '', repo_provider: str = 'github', repo_branch: str = 'main', 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, version: str | None = None, skip_undocumented: bool = True, recent_minor_versions: int = 2, get_versions_function: ~collections.abc.Callable[[str, str, int], list[str]] = <function get_versions_from_github>, generate_index_function: ~collections.abc.Callable[[...], None] = <function generate_index_md>, generate_docs_function: ~collections.abc.Callable[[...], None] = <function generate_documentation>, generate_redirect_function: ~collections.abc.Callable[[str], None] = <function generate_redirect_html>, get_conf_content_function: ~collections.abc.Callable[[...], str] = <function get_sphinx_conf_content>) → None[source]#

Update the Sphinx documentation.

Parameters:

  • root_path (str) – Root path of the project

  • project (str) – Name of the project

  • project_dir (str) – Path to the project directory (to be used with generate_docs_function)

  • author (str) – Author of the project

  • copyright (str) – Copyright information

  • html_logo (str) – URL to the logo

  • html_favicon (str) – URL to the favicon

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

  • github_user (str) – GitHub username

  • github_repo (str) – GitHub repository name

  • repo_url (str) – Repository URL used for source links, defaulting to the GitHub one built from the two above

  • 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”

  • edit_link_path (str) – Where the Sphinx sources are tracked, enabling the “edit this page” link, ex: “docs/source”

  • 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 stubs out instead of importing, defaulting to none

  • version (str | None) – Version to build documentation for (e.g. “1.0.0”, defaults to “latest”)

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

  • recent_minor_versions (int) – Number of recent minor versions to show all patches for. Defaults to 2

  • get_versions_function (Callable[[str, str, int], list[str]]) – Function to get versions from GitHub

  • generate_index_function (Callable[..., None]) – Function to generate index.md

  • generate_docs_function (Callable[..., None]) – Function to generate documentation

  • generate_redirect_function (Callable[[str], None]) – Function to create redirect file

  • get_conf_content_function (Callable[..., str]) – Function to get Sphinx conf.py content