plesty manual#

Generate reference manuals from an external device package’s DocDevice class.

generate#

plesty manual generate [--module-name MODULE] [--output-dir PATH] [--with-pdf]

Imports the device package from the project directory set via --project-dir (defaults to the current working directory), instantiates its DocDevice (or Device as a fallback), and calls .summary() to produce Markdown reference files. Optionally renders PDF versions using md2pdf.

Note

PDF generation requires the libpango system library (a dependency of weasyprint/md2pdf). Install it via your system package manager before using --with-pdf: brew install pango on macOS, apt install libpango-1.0-0 on Debian/Ubuntu.

Options#

Option

Default

Description

--module-name

inferred

Python module that exposes DocDevice. Defaults to the folder name with - replaced by _

--output-dir

<project-dir>/manual

Directory where generated files are written

--with-pdf

off

Also render PDF files from the generated Markdown

Output files#

File

Layout

short.md / short.pdf

Compact parameter list — portrait A4

table.md / table.pdf

Full parameter table — landscape A4

Module resolution#

The command attempts to import the module in this order:

  1. The value of --module-name if provided.

  2. The folder name of the project directory with - replaced by _.

  3. Any module discovered via __init__.py files under the project directory.

If the module exposes DocDevice, that is used. If only Device is found, it is used with a warning. The class is instantiated automatically if needed.

Examples#

# Generate Markdown manuals (run from inside the device project)
cd ../ape-pulse-slicer
plesty manual generate

# Or point directly at the project directory
plesty --project-dir ../ape-pulse-slicer manual generate

# Generate with PDF output
plesty --project-dir ../ape-pulse-slicer manual generate --with-pdf

# Override the inferred module name and output directory
plesty --project-dir ../ape-pulse-slicer manual generate \
  --module-name ape_pulse_slicer.doc \
  --output-dir ./manuals

DocDevice interface#

The device class must expose a summary method with the following signature:

def summary(self, *, style: str, filename: str) -> None:
    ...

style is either "short" or "md". The method should write the generated Markdown to filename.