Skip to content

Commit a13933b

Browse files
committed
chore: make doc-kit friendly
1 parent c334823 commit a13933b

35 files changed

Lines changed: 2999 additions & 1078 deletions

‎.changeset/bootstrap-command.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@nodejs/doc-kit': minor
3+
---
4+
5+
Add `doc-kit bootstrap [generators...]`

‎.changeset/install-command.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@nodejs/doc-kit': minor
3+
---
4+
5+
Add `doc-kit install [generators...]`

‎.changeset/serve-command.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@nodejs/doc-kit': minor
3+
---
4+
5+
Add `doc-kit serve`

‎README.md‎

Lines changed: 90 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -46,16 +46,26 @@ $ node packages/core/bin/cli.mjs --help
4646
```
4747
Usage: @nodejs/doc-kit [options] [command]
4848
49-
CLI tool to generate the Node.js API documentation
49+
CLI tool to generate API documentation
5050
5151
Options:
52-
--log-level <level> Log level (choices: "debug", "info", "warn", "error",
53-
"fatal", default: "info")
54-
-h, --help display help for command
52+
--log-level <level> Log level (choices: "debug", "info",
53+
"warn", "error", "fatal", default:
54+
"info")
55+
-h, --help display help for command
5556
5657
Commands:
57-
generate [options] Generate API docs
58-
help [command] display help for command
58+
bootstrap [options] [generators...] Set up a project for doc-kit: a
59+
configuration file wired to your
60+
package.json, a documentation directory,
61+
and the generator packages
62+
generate [options] Generate API docs
63+
install [options] [generators...] Install the packages providing built-in
64+
generators (defaults to the targets in
65+
your configuration file)
66+
serve [options] Generate API docs, serve them locally,
67+
and regenerate on changes
68+
help [command] display help for command
5969
```
6070

6171
### `generate`
@@ -78,14 +88,14 @@ Options:
7888
(json-simple, legacy-html, legacy-html-all,
7989
man-page, legacy-json, legacy-json-all,
8090
addon-verify, api-links, orama-db, llms-txt,
81-
sitemap, web) or an import specifier for a custom
82-
generator
91+
sitemap, html) or an import specifier for a
92+
custom generator
8393
--ignore <patterns...> Ignore file patterns (glob)
8494
-o, --output <directory> The output directory
8595
-p, --threads <number> Number of threads to use (minimum: 1)
8696
--chunk-size <number> Number of items to process per worker thread
8797
(minimum: 1)
88-
-v, --version <semver> Target Node.js version
98+
-v, --version <semver> Target project version
8999
-c, --changelog <url> Changelog URL or path
90100
--git-ref <ref> Git ref
91101
--index <url> index.md URL or path
@@ -94,6 +104,76 @@ Options:
94104
-h, --help display help for command
95105
```
96106

107+
### `serve`
108+
109+
Generates the documentation, serves it locally, and regenerates whenever the
110+
input files change — the fastest way to preview docs while writing them. It
111+
accepts the same configuration options as `generate`, plus:
112+
113+
```
114+
Options:
115+
--port <number> Preferred port (falls back to the next available
116+
one) (default: 3000)
117+
--static Serve the existing output as-is, without
118+
generating or watching
119+
```
120+
121+
### `bootstrap`
122+
123+
Sets a project up end to end: a `doc-kit.config.mjs` wired to your
124+
`package.json`, a documentation directory (detected, or created with a starter
125+
page), a `.gitignore` entry for the output, and the generator packages
126+
installed. Prompts for its few decisions on a TTY; `--yes` accepts the
127+
defaults. A new project only needs:
128+
129+
```sh
130+
npx doc-kit bootstrap && npx doc-kit serve
131+
```
132+
133+
```
134+
Usage: @nodejs/doc-kit bootstrap [options] [generators...]
135+
136+
Set up a project for doc-kit: a configuration file wired to your package.json, a
137+
documentation directory, and the generator packages
138+
139+
Arguments:
140+
generators Built-in generator names (json-simple, legacy-html,
141+
legacy-html-all, man-page, legacy-json,
142+
legacy-json-all, addon-verify, api-links, orama-db,
143+
llms-txt, sitemap, html)
144+
145+
Options:
146+
-y, --yes Accept all defaults without prompting
147+
--dir <path> The documentation directory
148+
-o, --output <directory> The output directory (default: "out")
149+
--force Overwrite an existing configuration file
150+
-h, --help display help for command
151+
```
152+
153+
### `install`
154+
155+
Installs the packages providing built-in generators (e.g. `doc-kit install html`
156+
installs `@nodejs/doc-kit-generator-react`). Without arguments, it installs
157+
whatever the `target` in your configuration file needs. The package manager is
158+
detected from the project lockfile.
159+
160+
```
161+
Usage: @nodejs/doc-kit install [options] [generators...]
162+
163+
Install the packages providing built-in generators (defaults to the targets in
164+
your configuration file)
165+
166+
Arguments:
167+
generators Built-in generator names (json-simple, legacy-html,
168+
legacy-html-all, man-page, legacy-json, legacy-json-all,
169+
addon-verify, api-links, orama-db, llms-txt, sitemap,
170+
html)
171+
172+
Options:
173+
--config-file <path> Config file
174+
-h, --help display help for command
175+
```
176+
97177
## Examples
98178

99179
### Legacy
@@ -126,5 +206,5 @@ npx doc-kit generate \
126206
> In order to use the search functionality, you _must_ serve the output directory.
127207
>
128208
> ```sh
129-
> npx serve out
209+
> npx doc-kit serve --static -o out
130210
> ```

‎docs/cli.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# CLI
2+
3+
The `doc-kit` command-line interface. Every option that maps to
4+
configuration can also live in a [configuration file](./configuration.md);
5+
when both are present, CLI flags win (rule of specifity).
6+
7+
```sh
8+
npx doc-kit [command] [options]
9+
```
10+
11+
One option applies to every command:
12+
13+
| Option | Description |
14+
| --------------------- | ------------------------------------------------------ |
15+
| `--log-level <level>` | `debug`, `info` (default), `warn`, `error`, or `fatal` |
16+
17+
## `doc-kit bootstrap`
18+
19+
```sh
20+
npx doc-kit bootstrap [options] [generators...]
21+
```
22+
23+
Sets a project up end to end: a `doc-kit.config.mjs` wired to your
24+
`package.json`, a documentation directory (detected, or created with a
25+
starter page), a `.gitignore` entry for the output, and the generator
26+
packages installed. On a terminal it prompts for its few decisions;
27+
otherwise (or with `--yes`) it accepts the defaults.
28+
29+
| Option | Description |
30+
| ---------------------- | --------------------------------------------- |
31+
| `[generators...]` | Built-in generator names. **Default:** `html` |
32+
| `-y`, `--yes` | Accept all defaults without prompting |
33+
| `--dir <path>` | The documentation directory |
34+
| `-o`, `--output <dir>` | The output directory. **Default:** `out` |
35+
| `--force` | Overwrite an existing configuration file |
36+
37+
## `doc-kit generate`
38+
39+
```sh
40+
npx doc-kit generate [options]
41+
```
42+
43+
Runs the generators and writes their output. Requires a `target` and an
44+
`input`, from flags or the configuration file.
45+
46+
| Option | Description |
47+
| ----------------------------- | ------------------------------------------------------------- |
48+
| `--config-file <path>` | Use a specific configuration file instead of searching |
49+
| `-i`, `--input <patterns...>` | Input file patterns (glob) |
50+
| `-t`, `--target <name...>` | Generator name(s), or import specifiers for custom generators |
51+
| `--ignore <patterns...>` | Input patterns to skip |
52+
| `-o`, `--output <dir>` | The output directory |
53+
| `-v`, `--version <semver>` | The version of the project being documented |
54+
| `-c`, `--changelog <url>` | Changelog URL or path (release history for version selectors) |
55+
| `--git-ref <ref>` | Git ref used in source links |
56+
| `--index <url>` | `index.md` URL or path |
57+
| `--minify` | Minify the output |
58+
| `--type-map <url>` | Type map URL or path (custom type-name → URL links) |
59+
| `-p`, `--threads <n>` | Worker threads to use (minimum 1) |
60+
| `--chunk-size <n>` | Items per worker thread (minimum 1) |
61+
62+
## `doc-kit serve`
63+
64+
```sh
65+
npx doc-kit serve [options]
66+
```
67+
68+
Generates the documentation, serves it locally, and regenerates whenever
69+
input files change — the writing loop. Accepts every `generate` option,
70+
plus:
71+
72+
| Option | Description |
73+
| ----------------- | ---------------------------------------------------------------------- |
74+
| `--port <number>` | Preferred port, falling back to the next free one. **Default:** `3000` |
75+
| `--static` | Serve the existing output as-is, without generating or watching |
76+
77+
`--static` is also the production preview: it serves any built output
78+
directory over HTTP, which the `html` output requires.
79+
80+
## `doc-kit install`
81+
82+
```sh
83+
npx doc-kit install [generators...]
84+
```
85+
86+
Installs the packages providing built-in generators — `doc-kit install html`
87+
installs `@nodejs/doc-kit-generator-react`. With no arguments, it installs
88+
whatever the `target` in your configuration file needs. The package manager
89+
is detected from your lockfile (npm, pnpm, yarn, or bun).
90+
91+
| Option | Description |
92+
| ---------------------- | ------------------------------------------------------ |
93+
| `[generators...]` | Built-in generator names |
94+
| `--config-file <path>` | Use a specific configuration file instead of searching |

0 commit comments

Comments
 (0)