stouputils.applications.automatic_docs.sphinx module#

Sphinx documentation generation utilities.

This module provides a comprehensive set of utilities for automatically generating and managing Sphinx documentation for Python projects. It handles the creation of configuration files, index pages, version management, and HTML generation.

Example of usage:

import stouputils as stp
from stouputils.applications import automatic_docs

if __name__ == "__main__":
    automatic_docs.sphinx_docs(
        root_path=stp.get_root_path(__file__, go_up=1),
        project="stouputils",
        author="Stoupy",
        copyright="2025, Stoupy",
        html_logo="https://avatars.githubusercontent.com/u/35665974",
        html_favicon="https://avatars.githubusercontent.com/u/35665974",
                    html_theme="breeze",    # Available themes: breeze, furo, pydata_sphinx_theme, sphinx_rtd_theme, or other you installed
        github_user="Stoupy51",
        github_repo="stouputils",
        version="1.2.0",
        skip_undocumented=True,
    )
check_dependencies(html_theme: str) → None[source]#

Check for each requirement if it is installed.

Parameters:

html_theme (str) – HTML theme to use for the documentation, to check if it is installed (e.g. “breeze”, “pydata_sphinx_theme”, “furo”, etc.)

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,
) → 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

  • 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

Returns:

Content of the Sphinx configuration file

Return type:

str

generate_index_md(readme_path: str, index_path: str, project: str, github_user: str, github_repo: str, get_versions_function: ~collections.abc.Callable[[str, str, int], list[str]] = <function get_versions_from_github>, recent_minor_versions: int = 2) → None[source]#

Generate index.md (MyST) from README.md content.

This keeps the README content as Markdown (no conversion) and uses the MyST toctree directive to include module docs.

Parameters:

  • readme_path (str) – Path to the README.md file

  • index_path (str) – Path where index.md should be created

  • project (str) – Name of the project

  • github_user (str) – GitHub username

  • github_repo (str) – GitHub repository name

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

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

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 = '', 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

  • 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