plesty.sdk.commands.docs.sphinx_builder

Sphinx app configuration and build process.

Functions

_toc_references_api(→ bool)	Return True when a toc node (or any child entry) points into reference/.
_api_index_docs(→ list[str])	Return the generated top-level package index documents for the scan.
_toc_with_api_reference(→ str)	Return the toc path to use, ensuring the API reference is in the tree.
_sidebar_title(→ str)	Return the module name the sidebar shows under the mark and the type pill.
make_sphinx_config(→ dict[str, Any])	Set up the Sphinx configuration dictionary customized for the project.
build_sphinx_app(→ sphinx.application.Sphinx)	Build the Sphinx application.

Module Contents

plesty.sdk.commands.docs.sphinx_builder._toc_references_api(node: Any) → bool

Return True when a toc node (or any child entry) points into reference/.

Parameters:

node (Any)

Return type:

bool

plesty.sdk.commands.docs.sphinx_builder._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/<name>/index; for a PEP-420 namespace root each child package documents at reference/<namespace>/<child>/index (autoapi’s own index toctree glob is one level deep and misses these, so the toc references them directly).

Parameters:

import_packages (list[str])

Return type:

list[str]

plesty.sdk.commands.docs.sphinx_builder._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.

Parameters:

• settings (plesty.sdk.context.DocumentationSettings)

• api_docs (list[str])

Return type:

str

plesty.sdk.commands.docs.sphinx_builder._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.

Parameters:

• site_name (str) – [tool.plesty.docs] site-name, or the project name.

• module_type (str | None) – [tool.plesty] module_type, or None.

Return type:

str

plesty.sdk.commands.docs.sphinx_builder.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 _sidebar_title()), and a left navigation tree.

Parameters:

• settings (plesty.sdk.context.DocumentationSettings) – The documentation settings.

• version_tag (str | None) – 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.

• theme_dir (os.PathLike[str]) – Directory containing the shared theme assets (plesty-hub.css, plesty-versions.js, plesty-logo.svg, plesty-mark.svg).

Returns:

The Sphinx configuration dictionary.

Return type:

dict[str, Any]

plesty.sdk.commands.docs.sphinx_builder.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.

Parameters:

• settings (plesty.sdk.context.DocumentationSettings) – The documentation settings.

• version_tag (str | None) – The version for which the documentation pages are built.

• build_dir (str) – The location where the documentation pages are built.

• delete_artifacts (bool) – Whether to delete Sphinx build artifacts.

• status (Any) – File-like object for Sphinx progress output. Defaults to sys.stdout. Pass io.StringIO() to suppress all output.

• warning (Any) – File-like object for Sphinx warning output. Defaults to sys.stderr. Pass io.StringIO() to capture warnings.

Returns:

The Sphinx application object.

Return type:

sphinx.application.Sphinx