plesty.sdk.commands.docs.generate

Zero-effort device documentation page generation (plesty-sdk#18).

A device module that declares module_type = "device" and exports a DocDevice (or Device) class gets its reference pages generated automatically from the live doc_model(): one page each for the device’s parameters, operations, and the shared standard methods. Authors write only the QuickStart (docs/index.md); everything else is derived from the schema so it never drifts from the code.

Attributes

`GENERATED_DIR`
`_GENERATED_PAGES`
`_DOCSTRING_SECTION`

Functions

`_module_name_from_toml`(→ str)	Derive the Python module name from the pyproject.toml package name.
`load_doc_device`(→ Any)	Import the device package and construct a hardware-free doc instance.
`_one_line`(→ str)	Collapse a value's whitespace to a single clean line.
`_summary`(→ str)	Reduce a docstring to its lead paragraph (drops Args/Returns sections).
`_dtype_str`(→ str)	Render a dtype (a `type` or an already-resolved name) as a string.
`_rst_escape`(→ str)	Escape reStructuredText emphasis/substitution characters in free text.
`_rst_badge`(→ str)	Render a sphinx-design badge as an inline reStructuredText role.
`_field_badge`(→ str)	Badge naming what this entry cost on hardware, or "" if untested.
`_param_badges`(→ list[str])	RST badges for a config parameter (unit, range/options, access).
`_signature`(→ str)	Build a Python-style call signature `name(arg: type = default) -> ret`.
`_field_desc`(→ str)	Describe a parameter/output: its text plus unit and range/options notes.
`_render_parameters`(→ str)	Render the grouped parameters as standard Python API reference blocks.
`_render_funcs`(→ str)	Render operations as standard Python API reference blocks.
`_first_param_key`(→ str)	Return the first parameter's full key (`group.name` for grouped params).
`_grouped_usage_block`(→ list[str])	Return Usage lines explaining grouped parameters, or empty if ungrouped.
`_render_usage`(→ str)	Render the Usage tutorial (local and remote-client access).
`render_device_pages`(→ dict[str, str])	Render every generated page for a device's doc model.
`_standard_device_toc`(→ str)	Return the standard device table of contents (QuickStart + reference).
`ensure_device_toc`(→ None)	Ensure the external TOC wires in the generated reference pages.
`generate_device_pages`(→ None)	Generate the reference pages for a device module, if it is one.

Module Contents

plesty.sdk.commands.docs.generate.GENERATED_DIR = '_generated'

plesty.sdk.commands.docs.generate._GENERATED_PAGES = (('usage', 'Usage'), ('parameters', 'Parameters'), ('functions', 'Functions'),...

plesty.sdk.commands.docs.generate._module_name_from_toml(pyproject_toml: dict[str, Any]) → str

Derive the Python module name from the pyproject.toml package name.

Parameters:: pyproject_toml (dict[str, Any])
Return type:: str

plesty.sdk.commands.docs.generate.load_doc_device(pyproject_toml: dict[str, Any]) → Any

Import the device package and construct a hardware-free doc instance.

Prefers the module’s DocDevice factory (a pre-addressed Device); falls back to Device with default arguments. Construction only loads schemas and registers parameters/operations — it never opens a connection — so the doc model is fully populated without hardware.

Parameters:: pyproject_toml (dict[str, Any]) – Parsed pyproject.toml content of the device project.
Returns:: A constructed device instance exposing doc_model().
Raises:: click.ClickException – If the package or a usable device class is missing.
Return type:: Any

plesty.sdk.commands.docs.generate._one_line(value: Any) → str

Collapse a value’s whitespace to a single clean line.

Parameters:: value (Any)
Return type:: str

plesty.sdk.commands.docs.generate._DOCSTRING_SECTION

plesty.sdk.commands.docs.generate._summary(text: Any) → str

Reduce a docstring to its lead paragraph (drops Args/Returns sections).

Signature parameters and outputs are already documented as their own entries, so the description keeps only the human-readable summary.

Parameters:: text (Any)
Return type:: str

plesty.sdk.commands.docs.generate._dtype_str(dtype: Any) → str

Render a dtype (a type or an already-resolved name) as a string.

Parameters:: dtype (Any)
Return type:: str

plesty.sdk.commands.docs.generate._rst_escape(text: str) → str

Escape reStructuredText emphasis/substitution characters in free text.

Docstring summaries and descriptions are emitted verbatim inside eval-rst blocks, so a stray * or | would otherwise trip the RST inline parser. Backticks are left intact so intentional double-backtick inline literals in docstrings still render.

Parameters:: text (str)
Return type:: str

plesty.sdk.commands.docs.generate._rst_badge(role: str, text: Any) → str

Render a sphinx-design badge as an inline reStructuredText role.

Parameters:

role (str)
text (Any)

Return type:

str

plesty.sdk.commands.docs.generate._field_badge(latencies: dict[str, float], name: str) → str

Badge naming what this entry cost on hardware, or “” if untested.

Only what a field test actually reached carries one. An entry with no badge was never exercised against an instrument, which is a different fact from one that was and answered quickly.

Parameters:

latencies (dict[str, float]) – Name → median milliseconds, from field_latencies.
name (str) – Parameter key or operation name.

Return type:

str

plesty.sdk.commands.docs.generate._param_badges(param: Any) → list[str]

RST badges for a config parameter (unit, range/options, access).

Type and default are shown in the py:attribute signature, so they are not repeated as badges.

Parameters:: param (Any)
Return type:: list[str]

plesty.sdk.commands.docs.generate._signature(f: Any) → str

Build a Python-style call signature name(arg: type = default) -> ret.

Parameters:: f (Any)
Return type:: str

plesty.sdk.commands.docs.generate._field_desc(spec: Any) → str

Describe a parameter/output: its text plus unit and range/options notes.

Parameters:: spec (Any)
Return type:: str

plesty.sdk.commands.docs.generate._render_parameters(parameters: dict[str, list[Any]], latencies: dict[str, float] | None = None) → str

Render the grouped parameters as standard Python API reference blocks.

Each parameter is emitted as a py:attribute directive (via eval-rst) so its name renders in the same signature style as an operation — a coloured name: type = default header — with the description and metadata pills (unit, range/options, access) in the body.

Parameters:

parameters (dict[str, list[Any]])
latencies (dict[str, float] | None)

Return type:

str

plesty.sdk.commands.docs.generate._render_funcs(title: str, intro: str, funcs: list[Any], latencies: dict[str, float] | None = None) → str

Render operations as standard Python API reference blocks.

Each operation is emitted as a py:function directive (via eval-rst) so it renders with the same signature + Parameters/Returns field lists as an autodoc API reference, decorated with a source shield (schema/custom).

Parameters:

title (str)
intro (str)
funcs (list[Any])
latencies (dict[str, float] | None)

Return type:

str

plesty.sdk.commands.docs.generate._first_param_key(parameters: dict[str, list[Any]]) → str

Return the first parameter’s full key (group.name for grouped params).

Parameters:: parameters (dict[str, list[Any]])
Return type:: str

plesty.sdk.commands.docs.generate._grouped_usage_block(parameters: dict[str, list[Any]]) → list[str]

Return Usage lines explaining grouped parameters, or empty if ungrouped.

Parameters:: parameters (dict[str, list[Any]])
Return type:: list[str]

plesty.sdk.commands.docs.generate._render_usage(doc_model: Any, module_name: str) → str

Render the Usage tutorial (local and remote-client access).

Parameters:

doc_model (Any)
module_name (str)

Return type:

str

plesty.sdk.commands.docs.generate.render_device_pages(doc_model: Any, module_name: str = 'device', latencies: dict[str, float] | None = None) → dict[str, str]

Render every generated page for a device’s doc model.

Parameters:

doc_model (Any) – A DeviceDocModel from device.doc_model().
module_name (str) – The device’s Python module name (plesty.<module_name>), used in the Usage tutorial’s import and server-launch examples.
latencies (dict[str, float] | None) – What each entry cost on hardware, from field_latencies(). Entries absent from it carry no measurement badge, which is how a reader tells “never exercised” from “exercised and fast”.

Returns:

Mapping of <slug> to the rendered markdown for that page.

Return type:

dict[str, str]

plesty.sdk.commands.docs.generate._standard_device_toc() → str

Return the standard device table of contents (QuickStart + reference).

Return type:: str

plesty.sdk.commands.docs.generate.ensure_device_toc(docs_dir: str, toc_file: str | None) → None

Ensure the external TOC wires in the generated reference pages.

Only writes when the current TOC does not already reference the generated directory, so an author who has taken ownership of toc.yaml keeps their customisation. QuickStart (index.md) is never touched.

Parameters:

docs_dir (str) – The documentation source directory.
toc_file (str | None) – Path to the external TOC file, or None if disabled.

Return type:

None

plesty.sdk.commands.docs.generate.generate_device_pages(settings: plesty.sdk.context.DocumentationSettings, pyproject_toml: dict[str, Any]) → None

Generate the reference pages for a device module, if it is one.

No-op for non-device modules. For device modules, imports the device, renders the parameter/function/standard-method pages into docs/_generated/ and ensures the TOC references them.

Parameters:

settings (plesty.sdk.context.DocumentationSettings) – The documentation settings (source dir, TOC path).
pyproject_toml (dict[str, Any]) – Parsed pyproject.toml content of the target project.

Return type:

None