Metadata-Version: 2.4
Name: documator
Version: 1.0.0
Summary: A documentation tool
Author-email: Martin Bernstorff <martinbernstorff@gmail.com>
Requires-Python: >=3.14
Requires-Dist: colorlog>=6.12.0
Requires-Dist: iterpy>=1.14.0
Requires-Dist: pydantic>=2.13.4
Requires-Dist: typer>=0.27.0
Requires-Dist: watchfiles>=1.2.0
Description-Content-Type: text/markdown

<!-- Generated by documator from README.md — edit the template, not this file. -->
# documator

A documentation CLI. This readme is itself rendered from `templates/README.md` into the repository root by the `documator render` command.

## Install

```
uv sync
```

## Usage

```
documator [--quiet] render INPUT_DIR OUTPUT_DIR [--watch] [--check] [--timeout SECONDS]
documator [--quiet] skills INPUT_DIR OUTPUT_DIR [--watch] [--timeout SECONDS]
```

`render` mirrors the input tree. 

```
                                                                                
 Usage: documator render [OPTIONS] {input_dir} {output_dir}                     
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    input_dir       <parse>  [required]                                     │
│ *    output_dir      <parse>  [required]                                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --watch                                                                      │
│ --check                                                                      │
│ --timeout        SECONDS  [default: root=10.0]                               │
│ --help                    Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

`--check` renders the whole tree and writes none of it: nothing is created, overwritten or pruned. Every output that is missing, out of date, or still tracked after its template went away is reported, and the run exits non-zero — so CI can fail on a repository whose generated files have drifted from their templates without the job being able to paper over it. Blocks still run, since their output is what the comparison is about; `--check` bounds what documator writes, not what a template's commands do. It cannot be combined with `--watch`.

`skills` compiles the same templates into the flat `<skill-name>/SKILL.md` layout Claude's skill loader expects: nesting in the input tree is organisational only, the filename stem becomes the skill name, and the frontmatter is generated — any keys the template declares pass through, and a declared `description` wins over the name-derived placeholder.

An example tree might look like:

```
my-templates/
├── foo.md
├── bar/
│   └── SKILL.md
├── _hidden.md
```

and would result in:

```
.skills/
├── foo/
│   └── SKILL.md
├── bar/
│   └── SKILL.md
```

```
                                                                                
 Usage: documator skills [OPTIONS] {input_dir} {output_dir}                     
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    input_dir       <parse>  [required]                                     │
│ *    output_dir      <parse>  [required]                                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --watch                                                                      │
│ --timeout        SECONDS  [default: root=10.0]                               │
│ --help                    Show this message and exit.                        │
╰──────────────────────────────────────────────────────────────────────────────╯
```

### Output

Every problem is logged where it arises and again at the end of the run, so a long render does not bury its errors above the scrollback. The run closes with a count — `12 files, 1 warning, 2 errors` — followed by the warnings and then the errors, worst news nearest the prompt. Under `--watch` each recompile closes the same way, since a session has no other end to report at.

Log lines are coloured by level when stderr is a terminal, and plain when it is a pipe or when `NO_COLOR` is set. `--quiet` drops the per-file chatter and keeps warnings, errors and the summary; a quiet run that prints nothing is a run that had nothing to report.

### Try it

```sh
mkdir -p docs/guides/plan/references out compiled
printf '# Review\n\nRead the diff before the description.\n' > docs/guides/review.md
printf -- '---\ndescription: Plan a change\n---\n# Plan\n' > docs/guides/plan/SKILL.md
echo '# Spec' > docs/guides/plan/references/spec.md
uv run documator render docs out
uv run documator skills docs compiled
```

Two layouts over one tree. `render` mirrors it into `out/`, so `guides/review.md` stays `guides/review.md`. `skills` flattens it into `compiled/`: the bare `guides/review.md` becomes `review/SKILL.md` with a name-derived `description`, and the `guides/plan/` folder becomes `plan/SKILL.md` — carrying its declared `description` through — with `references/spec.md` bundled beside it as `plan/references/spec.md`.

This block is extracted verbatim and run by `test_readme.py`.
