plesty docs

Build, preview, and deploy the Sphinx documentation for a Plesty project.

Subcommands

• plesty docs serve — local preview with live reload

• plesty docs deploy — publish to a remote pages branch

What a build contains

Every PLESTY module — core, device, experiment, analyzer — builds with the standard Read-the-Docs theme: a sidebar header with the PLESTY mark beside a pill naming the module type ([tool.plesty] module_type, in its type colour) and the module name below it, a version picker in the sidebar header once the module has releases to pick between, a titles-only left navigation tree, and the shared stylesheet (identifier table columns never wrap; prose columns do).

[mark] (EXPERIMENT)
Perovskite G2 Search

The name is site-name without a leading “Plesty” and without a trailing type word — the mark and the pill already say them: Plesty Perovskite G2 Search Experiment reads “Perovskite G2 Search”.

Content comes from three sources:

1. Hand-written pages from the configured docs directory (Markdown via MyST or reStructuredText), ordered by toc.yaml if present (sphinx-external-toc).

2. Generated API reference (always on): autoapi scans the project’s packages — including PEP-420 namespace packages such as plesty/<module> — and renders the full module tree under reference/, nested hierarchically in the sidebar. If the project’s toc.yaml does not place the reference itself, an API Reference entry is appended as the last item of the navigation automatically. Directories listed in api-ignore are skipped.

3. Generated device reference (device modules): the pages under docs/_generated/ — Usage, Parameters, Functions, Standard Methods — are rendered from the device’s live doc_model() and wired into the toc automatically; no hand-written reference content is needed.

---

serve

plesty docs serve [--dev-addr IP:PORT]

Starts a local web server that renders the project documentation and automatically reloads whenever a .md or .rst file changes. Useful during active documentation writing.

Options

Option	Default	Description
--dev-addr	localhost:8000	Host and port for the preview server

Example

# Default address
plesty docs serve

# Listen on all interfaces at a custom port
plesty docs serve --dev-addr 0.0.0.0:9000

Press Ctrl+C to stop the server.

---

deploy

plesty docs deploy REMOTE_URL TARGET_BRANCH (--release | --latest)

Builds the Sphinx documentation and pushes it to TARGET_BRANCH on the repository at REMOTE_URL, suitable for GitLab Pages. The branch is created as an orphan if it does not yet exist.

--release and --latest are mutually exclusive and one is required:

Flag	Behaviour
--latest	Publishes to html/latest/ — for commits to the default branch
--release	Publishes to html/releases/<major>.<minor>/ — for tagged releases

Example

# Deploy development snapshot (latest)
plesty docs deploy \
  https://oauth2:${CI_BOT_TOKEN}@gitlab.com/plesty/my-device.git \
  docs-build \
  --latest

# Deploy a versioned release
plesty docs deploy \
  https://oauth2:${CI_BOT_TOKEN}@gitlab.com/plesty/my-device.git \
  docs-build \
  --release

In practice this command is called by the hub-deploy-docs job of the plesty-standard-ci component and does not need to be run manually.

---

Configuration — [tool.plesty.docs]

All keys are optional and live in the project’s pyproject.toml:

Key	Default	Meaning
site-name	[project].name	Module name shown under the mark (a leading “Plesty” and a trailing type word are dropped)
docs-dir	docs	Directory containing the documentation sources
toc-file	toc.yaml	External toc file inside docs-dir; set "" to disable
api-ignore	[]	Top-level package directories excluded from the API scan (e.g. a deprecated compat shim)

The API reference itself is always generated (no switch); a project controls its sidebar position by placing a reference/… entry in toc.yaml, and its scope via api-ignore.

Example (plesty-lib):

[tool.plesty.docs]
site-name = "LIB"
docs-dir = "docs"
api-ignore = ["plestylib"]