Auf dieser Seite

Generierte Dokumentation Neu in Clay 4

Manche Seiten schreibt am besten ein Werkzeug: die API-Referenz einer Bibliothek aus ihrem Code und ihren Kommentaren, oder eine Liste der Optionen einer Kommandozeile. generate in der clay.yaml führt solche Werkzeuge vor jedem clay build, clay dev und clay check aus. So sind die erzeugten Seiten immer aktuell und gehören zur Seite wie alle anderen.

generate:
  - npx typedoc --plugin typedoc-plugin-markdown --entryFileName index --out docs/api src/index.ts

Die Befehle laufen im Projektordner, einer nach dem anderen. Was sie in docs/ schreiben, wird zu Seiten: in der Navigation, der Suche, den Linkprüfungen und dem Markdown für Agenten.

Tipp

Diese Website erzeugt ihre CLI-Referenz aus Clays eigener Hilfe, mit einem Skript von ein paar Zeilen: scripts/cli-reference.mjs.

#API-Referenz aus dem Code

Jedes Werkzeug, das Markdown schreibt, funktioniert:

TypeDoc mit typedoc-plugin-markdown:

npm install --save-dev typedoc typedoc-plugin-markdown

generate:
  - npx typedoc --plugin typedoc-plugin-markdown --entryFileName index --out docs/api src/index.ts

gomarkdoc:

go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@latest

generate:
  - gomarkdoc --output docs/api/index.md ./...

pydoc-markdown:

pip install pydoc-markdown

generate:
  - pydoc-markdown -I src -m my_package > docs/api.md

Halte erzeugte Seiten aus Git heraus. Sie entstehen bei jedem Build neu:
.gitignore
```
docs/api/
```
in der .gitignore.
Installiere das Werkzeug auch in der CI, vor npx clay build --strict: als Dev-Abhängigkeit in der package.json oder mit einem eigenen Schritt.
Schreib drumherum. Eine index.md im Ordner gibt den erzeugten Seiten Titel, Icon und eine Einleitung, solange das Werkzeug keine eigene schreibt. Siehe Index-Seiten.

#Wenn ein Befehl scheitert

Der Build hält an und zeigt die letzten Zeilen des Befehls:

✖  Generating docs: npx typedoc --out docs/api src/index.ts
│  [error] The entry point src/index.ts does not exist
│  Failed with exit code 1
│
└  Build failed after 2.1s. Run "clay build --verbose" for the full output.

clay check --json meldet dieselben Zeilen als Probleme.

Hinweis

Die Befehle in der clay.yaml laufen auf jedem Rechner, der die Dokumentation baut, wie die Skripte in der package.json. Prüf Änderungen daran wie Code.