stouputils.applications.automatic_docs.zensical module#

Zensical documentation generation utilities.

This module provides a comprehensive set of utilities for automatically generating and managing documentation for Python projects using Zensical (a modern static site generator based on MkDocs Material) and mkdocstrings for API reference generation from docstrings.

It handles the creation of configuration files, index pages, API reference pages, version management, and HTML generation.

Example of usage:

import stouputils as stp
from stouputils.applications import automatic_docs

if __name__ == "__main__":
    automatic_docs.zensical_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",
        github_user="Stoupy51",
        github_repo="stouputils",
        version="1.2.0",
        skip_undocumented=True,
    )
get_zensical_config_content(
project: str,
project_dir: str,
docs_dir: str,
site_dir: str,
author: str,
current_version: str,
copyright: str,
html_logo: str,
html_favicon: str,
github_user: str = '',
github_repo: str = '',
version_list: list[str] | None = None,
skip_undocumented: bool = True,
api_pages: list[tuple[str, str]] | None = None,
) → str[source]#

Get the content of the Zensical configuration file (zensical.toml).

Parameters:

  • project (str) – Name of the project

  • project_dir (str) – Path to the project directory

  • docs_dir (str) – Path to the docs source directory (relative to root)

  • site_dir (str) – Path to the build output directory (relative to root)

  • author (str) – Author of the project

  • current_version (str) – Current version

  • copyright (str) – Copyright information

  • html_logo (str) – Path to the logo image (relative to docs_dir)

  • html_favicon (str) – Path to the favicon image (relative to docs_dir)

  • 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

  • api_pages (list[tuple[str, str]] | None) – List of (module_name, md_filename) tuples for nav

Returns:

Content of the Zensical configuration file (TOML)

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 from README.md content.

This keeps the README content as Markdown and creates the home page for the Zensical documentation. Navigation to API docs is handled by the Zensical config (nav or auto-discovery).

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_api_pages(
api_dir: str,
project: str,
project_dir: str,
) → list[tuple[str, str]][source]#

Walk the project directory and generate Markdown pages with ::: directives for mkdocstrings API documentation.

Parameters:

  • api_dir (str) – Directory where API markdown pages should be written

  • project (str) – Name of the project (package name)

  • project_dir (str) – Path to the project directory (Python package root)

Returns:

List of (module_name, md_filename) tuples

Return type:

list[tuple[str, str]]

generate_documentation(
config_path: str,
root_path: str,
) → None[source]#

Generate documentation using Zensical.

Parameters:

  • config_path (str) – Path to the zensical.toml configuration file

  • root_path (str) – Root path of the project (working directory for the build)

zensical_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 = '', 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_api_pages_function: ~collections.abc.Callable[[...], list[tuple[str, str]]] = <function generate_api_pages>, generate_docs_function: ~collections.abc.Callable[[...], None] = <function generate_documentation>, generate_redirect_function: ~collections.abc.Callable[[str], None] = <function generate_redirect_html>, get_config_content_function: ~collections.abc.Callable[[...], str] = <function get_zensical_config_content>) → None[source]#

Update the documentation using Zensical and mkdocstrings.

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 or path to the logo image

  • html_favicon (str) – URL or path to the favicon image

  • html_theme (str) – Unused (kept for backward compatibility)

  • 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_api_pages_function (Callable[..., list[tuple[str, str]]]) – Function to generate API pages

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

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

  • get_config_content_function (Callable[..., str]) – Function to get Zensical config content