# plesty manual

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

## generate

```bash
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](https://github.com/jmaupetit/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

```bash
# 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:

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

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