plesty.sdk.commands.docs.sphinx_builder ======================================= .. py:module:: plesty.sdk.commands.docs.sphinx_builder .. autoapi-nested-parse:: Sphinx app configuration and build process. Functions --------- .. autoapisummary:: plesty.sdk.commands.docs.sphinx_builder._toc_references_api plesty.sdk.commands.docs.sphinx_builder._api_index_docs plesty.sdk.commands.docs.sphinx_builder._toc_with_api_reference plesty.sdk.commands.docs.sphinx_builder._sidebar_title plesty.sdk.commands.docs.sphinx_builder.make_sphinx_config plesty.sdk.commands.docs.sphinx_builder.build_sphinx_app Module Contents --------------- .. py:function:: _toc_references_api(node: Any) -> bool Return True when a toc node (or any child entry) points into reference/. .. py:function:: _api_index_docs(import_packages: list[str]) -> list[str] Return the generated top-level package index documents for the scan. Regular packages document at ``reference//index``; for a PEP-420 namespace root each child package documents at ``reference///index`` (autoapi's own index toctree glob is one level deep and misses these, so the toc references them directly). .. py:function:: _toc_with_api_reference(settings: plesty.sdk.context.DocumentationSettings, api_docs: list[str]) -> str Return the toc path to use, ensuring the API reference is in the tree. When the project's ``toc.yaml`` does not place the generated reference itself, a final "API Reference" entry is appended (so the reference is always the last item of the navigation), with the generated package indexes as its children, and the merged toc is written to the ``.plesty`` cache. .. py:function:: _sidebar_title(site_name: str, module_type: str | None) -> str Return the module name the sidebar shows under the mark and the type pill. The mark already says "Plesty" and the pill the module type, so a leading "Plesty" and a trailing type word are dropped: "Plesty Perovskite G2 Search Experiment" with ``module_type = "experiment"`` reads "Perovskite G2 Search". A name that is nothing but those words is kept as it is. :param site_name: ``[tool.plesty.docs] site-name``, or the project name. :param module_type: ``[tool.plesty] module_type``, or ``None``. .. py:function:: make_sphinx_config(settings: plesty.sdk.context.DocumentationSettings, version_tag: str | None, theme_dir: os.PathLike[str]) -> dict[str, Any] Set up the Sphinx configuration dictionary customized for the project. Every PLESTY module — core, device, experiment, analyzer — builds its documentation with the classic Read-the-Docs theme: a Plesty-cyan nav header carrying the Plesty mark beside the module-type pill, with the module name below it (see :func:`_sidebar_title`), and a left navigation tree. :param settings: The documentation settings. :param version_tag: The version for which the documentation pages are built; shown by the theme when set, and the version the sidebar picker marks as current. ``None`` builds the latest development docs. :param theme_dir: Directory containing the shared theme assets (``plesty-hub.css``, ``plesty-versions.js``, ``plesty-logo.svg``, ``plesty-mark.svg``). :returns: The Sphinx configuration dictionary. .. py:function:: build_sphinx_app(settings: plesty.sdk.context.DocumentationSettings, version_tag: str | None, build_dir: str, delete_artifacts: bool, status: Any = None, warning: Any = None) -> sphinx.application.Sphinx Build the Sphinx application. :param settings: The documentation settings. :param version_tag: The version for which the documentation pages are built. :param build_dir: The location where the documentation pages are built. :param delete_artifacts: Whether to delete Sphinx build artifacts. :param status: File-like object for Sphinx progress output. Defaults to ``sys.stdout``. Pass ``io.StringIO()`` to suppress all output. :param warning: File-like object for Sphinx warning output. Defaults to ``sys.stderr``. Pass ``io.StringIO()`` to capture warnings. :returns: The Sphinx application object.