plesty.sdk.commands.docs.generate ================================= .. py:module:: plesty.sdk.commands.docs.generate .. autoapi-nested-parse:: 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 ---------- .. autoapisummary:: plesty.sdk.commands.docs.generate.GENERATED_DIR plesty.sdk.commands.docs.generate._GENERATED_PAGES plesty.sdk.commands.docs.generate._DOCSTRING_SECTION Functions --------- .. autoapisummary:: plesty.sdk.commands.docs.generate._module_name_from_toml plesty.sdk.commands.docs.generate.load_doc_device plesty.sdk.commands.docs.generate._one_line plesty.sdk.commands.docs.generate._summary plesty.sdk.commands.docs.generate._dtype_str plesty.sdk.commands.docs.generate._rst_escape plesty.sdk.commands.docs.generate._rst_badge plesty.sdk.commands.docs.generate._field_badge plesty.sdk.commands.docs.generate._param_badges plesty.sdk.commands.docs.generate._signature plesty.sdk.commands.docs.generate._field_desc plesty.sdk.commands.docs.generate._render_parameters plesty.sdk.commands.docs.generate._render_funcs plesty.sdk.commands.docs.generate._first_param_key plesty.sdk.commands.docs.generate._grouped_usage_block plesty.sdk.commands.docs.generate._render_usage plesty.sdk.commands.docs.generate.render_device_pages plesty.sdk.commands.docs.generate._standard_device_toc plesty.sdk.commands.docs.generate.ensure_device_toc plesty.sdk.commands.docs.generate.generate_device_pages Module Contents --------------- .. py:data:: GENERATED_DIR :value: '_generated' .. py:data:: _GENERATED_PAGES :value: (('usage', 'Usage'), ('parameters', 'Parameters'), ('functions', 'Functions'),... .. py:function:: _module_name_from_toml(pyproject_toml: dict[str, Any]) -> str Derive the Python module name from the pyproject.toml package name. .. py:function:: 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. :param pyproject_toml: 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. .. py:function:: _one_line(value: Any) -> str Collapse a value's whitespace to a single clean line. .. py:data:: _DOCSTRING_SECTION .. py:function:: _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. .. py:function:: _dtype_str(dtype: Any) -> str Render a dtype (a ``type`` or an already-resolved name) as a string. .. py:function:: _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. .. py:function:: _rst_badge(role: str, text: Any) -> str Render a sphinx-design badge as an inline reStructuredText role. .. py:function:: _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. :param latencies: Name → median milliseconds, from ``field_latencies``. :param name: Parameter key or operation name. .. py:function:: _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. .. py:function:: _signature(f: Any) -> str Build a Python-style call signature ``name(arg: type = default) -> ret``. .. py:function:: _field_desc(spec: Any) -> str Describe a parameter/output: its text plus unit and range/options notes. .. py:function:: _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. .. py:function:: _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). .. py:function:: _first_param_key(parameters: dict[str, list[Any]]) -> str Return the first parameter's full key (``group.name`` for grouped params). .. py:function:: _grouped_usage_block(parameters: dict[str, list[Any]]) -> list[str] Return Usage lines explaining grouped parameters, or empty if ungrouped. .. py:function:: _render_usage(doc_model: Any, module_name: str) -> str Render the Usage tutorial (local and remote-client access). .. py:function:: 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. :param doc_model: A ``DeviceDocModel`` from ``device.doc_model()``. :param module_name: The device's Python module name (``plesty.``), used in the Usage tutorial's import and server-launch examples. :param latencies: What each entry cost on hardware, from :func:`~plesty.sdk.report.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 ```` to the rendered markdown for that page. .. py:function:: _standard_device_toc() -> str Return the standard device table of contents (QuickStart + reference). .. py:function:: 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. :param docs_dir: The documentation source directory. :param toc_file: Path to the external TOC file, or ``None`` if disabled. .. py:function:: 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. :param settings: The documentation settings (source dir, TOC path). :param pyproject_toml: Parsed pyproject.toml content of the target project.