Skip to content

Commit a5fec08

Browse files
lukekarrysfritzy
lukekarrys
authored and
fritzy
committed
feat: rewrite docs generation
High level overview of the changes here: - The source for the docs content has moved from `docs/content/` to `docs/lib/content/`. The generated markdown is still written to `docs/content/` but that directory is now ignored from git. - All generated content sections of the docs have been removed and replaced with single placeholder html comments such as `<!-- AUTOGENERATED CONFIG DESCRIPTIONS -->` - Placeholders are replaced with generated content only as part of the `prepack` step, so generated markdown is no longer checked in to source and all docs related `make` commands have been removed - All docs (and docs related) snapshots have been moved to a single test file that outputs command usage and formats it with functions imported from `docs/lib/index.js`. So tests will fail if docs content changes until `npm run snap` is run.
1 parent bf53d6d commit a5fec08

File tree

176 files changed

+10110
-21428
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

176 files changed

+10110
-21428
lines changed

‎.github/workflows/ci-docs.yml renamed to ‎.github/workflows/ci-npmcli-docs.yml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# This file is automatically added by @npmcli/template-oss. Do not edit.
22

3-
name: CI - docs
3+
name: CI - @npmcli/docs
44

55
on:
66
workflow_dispatch:
@@ -71,9 +71,9 @@ jobs:
7171
- name: Reset Deps
7272
run: node . run resetdeps
7373
- name: Lint
74-
run: node . run lint --ignore-scripts -w docs
74+
run: node . run lint --ignore-scripts -w @npmcli/docs
7575
- name: Post Lint
76-
run: node . run postlint --ignore-scripts -w docs
76+
run: node . run postlint --ignore-scripts -w @npmcli/docs
7777

7878
test:
7979
name: Test - ${{ matrix.platform.name }} - ${{ matrix.node-version }}
@@ -119,7 +119,7 @@ jobs:
119119
- name: Add Problem Matcher
120120
run: echo "::add-matcher::.github/matchers/tap.json"
121121
- name: Test
122-
run: node . test --ignore-scripts -w docs
122+
run: node . test --ignore-scripts -w @npmcli/docs
123123
- name: Check Git Status
124124
if: matrix && matrix.platform.os != 'windows-latest'
125125
run: node scripts/git-dirty.js

‎.github/workflows/ci.yml

Lines changed: 0 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -135,32 +135,6 @@ jobs:
135135
if: matrix && matrix.platform.os != 'windows-latest'
136136
run: node scripts/git-dirty.js
137137

138-
check-docs:
139-
name: Check Docs
140-
if: github.repository_owner == 'npm'
141-
runs-on: ubuntu-latest
142-
defaults:
143-
run:
144-
shell: bash
145-
steps:
146-
- name: Checkout
147-
uses: actions/checkout@v3
148-
- name: Setup Git User
149-
run: |
150-
git config --global user.email "npm-cli+bot@github.com"
151-
git config --global user.name "npm CLI robot"
152-
- name: Setup Node
153-
uses: actions/setup-node@v3
154-
with:
155-
node-version: 18.x
156-
cache: npm
157-
- name: Reset Deps
158-
run: node . run resetdeps
159-
- name: Make Docs
160-
run: make freshdocs
161-
- name: Check Git Status
162-
run: node scripts/git-dirty.js
163-
164138
licenses:
165139
name: Check Licenses
166140
if: github.repository_owner == 'npm'

‎.github/workflows/create-cli-deps-pr.yml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,6 @@ jobs:
6464
echo "Prepping CLI repo for release"
6565
cd cli
6666
git checkout "$npm_vtag"
67-
make
6867
make release
6968
7069
echo "Removing old npm"

‎DEPENDENCIES.md

Lines changed: 36 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,7 @@ graph LR;
119119
npm-->npmcli-arborist["@npmcli/arborist"];
120120
npm-->npmcli-ci-detect["@npmcli/ci-detect"];
121121
npm-->npmcli-config["@npmcli/config"];
122+
npm-->npmcli-docs["@npmcli/docs"];
122123
npm-->npmcli-eslint-config["@npmcli/eslint-config"];
123124
npm-->npmcli-fs["@npmcli/fs"];
124125
npm-->npmcli-git["@npmcli/git"];
@@ -192,6 +193,10 @@ graph LR;
192193
npmcli-config-->proc-log;
193194
npmcli-config-->read-package-json-fast;
194195
npmcli-config-->semver;
196+
npmcli-docs-->ignore-walk;
197+
npmcli-docs-->npmcli-eslint-config["@npmcli/eslint-config"];
198+
npmcli-docs-->npmcli-fs["@npmcli/fs"];
199+
npmcli-docs-->npmcli-template-oss["@npmcli/template-oss"];
195200
npmcli-fs-->semver;
196201
npmcli-git-->npm-pick-manifest;
197202
npmcli-git-->npmcli-promise-spawn["@npmcli/promise-spawn"];
@@ -255,6 +260,7 @@ graph LR;
255260
ansi-styles-->color-convert;
256261
are-we-there-yet-->delegates;
257262
are-we-there-yet-->readable-stream;
263+
argparse-->sprintf-js;
258264
babel-code-frame-->babel-highlight["@babel/highlight"];
259265
babel-core-->babel-code-frame["@babel/code-frame"];
260266
babel-core-->babel-generator["@babel/generator"];
@@ -273,13 +279,10 @@ graph LR;
273279
babel-core-->semver;
274280
babel-core-->source-map;
275281
babel-generator-->babel-types["@babel/types"];
282+
babel-generator-->jridgewell-gen-mapping["@jridgewell/gen-mapping"];
276283
babel-generator-->jsesc;
277-
babel-generator-->source-map;
278-
babel-helper-environment-visitor-->babel-types["@babel/types"];
279-
babel-helper-function-name-->babel-helper-get-function-arity["@babel/helper-get-function-arity"];
280284
babel-helper-function-name-->babel-template["@babel/template"];
281285
babel-helper-function-name-->babel-types["@babel/types"];
282-
babel-helper-get-function-arity-->babel-types["@babel/types"];
283286
babel-helper-hoist-variables-->babel-types["@babel/types"];
284287
babel-helper-module-imports-->babel-types["@babel/types"];
285288
babel-helper-module-transforms-->babel-helper-environment-visitor["@babel/helper-environment-visitor"];
@@ -325,6 +328,7 @@ graph LR;
325328
babel-traverse-->babel-types["@babel/types"];
326329
babel-traverse-->debug;
327330
babel-traverse-->globals;
331+
babel-types-->babel-helper-string-parser["@babel/helper-string-parser"];
328332
babel-types-->babel-helper-validator-identifier["@babel/helper-validator-identifier"];
329333
babel-types-->to-fast-properties;
330334
bin-links-->cmd-shim;
@@ -338,7 +342,6 @@ graph LR;
338342
bl-->inherits;
339343
bl-->readable-stream;
340344
brace-expansion-->balanced-match;
341-
brace-expansion-->concat-map;
342345
buffer-->base64-js;
343346
buffer-->ieee754;
344347
builtins-->semver;
@@ -376,7 +379,6 @@ graph LR;
376379
columnify-->strip-ansi;
377380
columnify-->wcwidth;
378381
combined-stream-->delayed-stream;
379-
convert-source-map-->safe-buffer;
380382
cssstyle-->cssom;
381383
data-urls-->abab;
382384
data-urls-->whatwg-mimetype;
@@ -387,18 +389,6 @@ graph LR;
387389
detab-->repeat-string;
388390
dezalgo-->asap;
389391
dezalgo-->wrappy;
390-
docs-->cmark-gfm;
391-
docs-->jsdom;
392-
docs-->marked-man;
393-
docs-->mdx-js-mdx["@mdx-js/mdx"];
394-
docs-->mkdirp;
395-
docs-->npmcli-eslint-config["@npmcli/eslint-config"];
396-
docs-->npmcli-fs["@npmcli/fs"];
397-
docs-->npmcli-promise-spawn["@npmcli/promise-spawn"];
398-
docs-->npmcli-template-oss["@npmcli/template-oss"];
399-
docs-->tap;
400-
docs-->which;
401-
docs-->yaml;
402392
domexception-->webidl-conversions;
403393
encoding-->iconv-lite;
404394
end-of-stream-->once;
@@ -410,6 +400,7 @@ graph LR;
410400
form-data-->asynckit;
411401
form-data-->combined-stream;
412402
form-data-->mime-types;
403+
front-matter-->js-yaml;
413404
fs-minipass-->minipass;
414405
gauge-->aproba;
415406
gauge-->console-control-strings;
@@ -483,6 +474,13 @@ graph LR;
483474
is-cidr-->cidr-regex;
484475
is-core-module-->has;
485476
is-fullwidth-code-point-->number-is-nan;
477+
jridgewell-gen-mapping-->jridgewell-set-array["@jridgewell/set-array"];
478+
jridgewell-gen-mapping-->jridgewell-sourcemap-codec["@jridgewell/sourcemap-codec"];
479+
jridgewell-gen-mapping-->jridgewell-trace-mapping["@jridgewell/trace-mapping"];
480+
jridgewell-trace-mapping-->jridgewell-resolve-uri["@jridgewell/resolve-uri"];
481+
jridgewell-trace-mapping-->jridgewell-sourcemap-codec["@jridgewell/sourcemap-codec"];
482+
js-yaml-->argparse;
483+
js-yaml-->esprima;
486484
jsdom-->abab;
487485
jsdom-->acorn-globals;
488486
jsdom-->acorn;
@@ -697,7 +695,6 @@ graph LR;
697695
npm-->cli-columns;
698696
npm-->cli-table3;
699697
npm-->columnify;
700-
npm-->docs;
701698
npm-->fastest-levenshtein;
702699
npm-->fs-minipass;
703700
npm-->glob;
@@ -741,6 +738,7 @@ graph LR;
741738
npm-->npmcli-arborist["@npmcli/arborist"];
742739
npm-->npmcli-ci-detect["@npmcli/ci-detect"];
743740
npm-->npmcli-config["@npmcli/config"];
741+
npm-->npmcli-docs["@npmcli/docs"];
744742
npm-->npmcli-eslint-config["@npmcli/eslint-config"];
745743
npm-->npmcli-fs["@npmcli/fs"];
746744
npm-->npmcli-git["@npmcli/git"];
@@ -847,6 +845,19 @@ graph LR;
847845
npmcli-config-->semver;
848846
npmcli-config-->walk-up-path;
849847
npmcli-disparity-colors-->ansi-styles;
848+
npmcli-docs-->cmark-gfm;
849+
npmcli-docs-->front-matter;
850+
npmcli-docs-->ignore-walk;
851+
npmcli-docs-->isaacs-string-locale-compare["@isaacs/string-locale-compare"];
852+
npmcli-docs-->jsdom;
853+
npmcli-docs-->marked-man;
854+
npmcli-docs-->mdx-js-mdx["@mdx-js/mdx"];
855+
npmcli-docs-->mkdirp;
856+
npmcli-docs-->npmcli-eslint-config["@npmcli/eslint-config"];
857+
npmcli-docs-->npmcli-fs["@npmcli/fs"];
858+
npmcli-docs-->npmcli-template-oss["@npmcli/template-oss"];
859+
npmcli-docs-->tap;
860+
npmcli-docs-->yaml;
850861
npmcli-fs-->gar-promisify["@gar/promisify"];
851862
npmcli-fs-->semver;
852863
npmcli-git-->lru-cache;
@@ -1042,6 +1053,7 @@ graph LR;
10421053
tough-cookie-->psl;
10431054
tough-cookie-->punycode;
10441055
tough-cookie-->universalify;
1056+
tough-cookie-->url-parse;
10451057
tr46-->punycode;
10461058
tunnel-agent-->safe-buffer;
10471059
type-check-->prelude-ls;
@@ -1065,6 +1077,8 @@ graph LR;
10651077
unist-util-visit-->unist-util-visit-parents;
10661078
unist-util-visit-parents-->types-unist["@types/unist"];
10671079
unist-util-visit-parents-->unist-util-is;
1080+
url-parse-->querystringify;
1081+
url-parse-->requires-port;
10681082
validate-npm-package-license-->spdx-correct;
10691083
validate-npm-package-license-->spdx-expression-parse;
10701084
validate-npm-package-name-->builtins;
@@ -1102,6 +1116,6 @@ packages higher up the chain.
11021116
- pacote, libnpmaccess, libnpmhook, libnpmorg, libnpmsearch, libnpmteam, npm-profile
11031117
- npm-registry-fetch, libnpmversion
11041118
- @npmcli/git, make-fetch-happen, @npmcli/config, init-package-json
1105-
- @npmcli/installed-package-contents, @npmcli/map-workspaces, cacache, npm-pick-manifest, @npmcli/run-script, read-package-json, @npmcli/query, readdir-scoped-modules, promzard
1106-
- npm-bundled, read-package-json-fast, @npmcli/fs, unique-filename, @npmcli/promise-spawn, npm-install-checks, npm-package-arg, npm-packlist, normalize-package-data, @npmcli/package-json, bin-links, nopt, npmlog, parse-conflict-json, dezalgo, read
1107-
- npm-normalize-package-bin, @npmcli/name-from-folder, json-parse-even-better-errors, semver, @npmcli/move-file, fs-minipass, infer-owner, ssri, unique-slug, hosted-git-info, proc-log, validate-npm-package-name, @npmcli/node-gyp, ignore-walk, minipass-fetch, cmd-shim, read-cmd-shim, write-file-atomic, abbrev, are-we-there-yet, gauge, wrappy, treeverse, @npmcli/eslint-config, @npmcli/template-oss, minify-registry-metadata, @npmcli/disparity-colors, @npmcli/ci-detect, mute-stream, ini, npm-audit-report, npm-user-validate
1119+
- @npmcli/docs, @npmcli/installed-package-contents, @npmcli/map-workspaces, cacache, npm-pick-manifest, @npmcli/run-script, read-package-json, @npmcli/query, readdir-scoped-modules, promzard
1120+
- @npmcli/fs, npm-bundled, read-package-json-fast, unique-filename, @npmcli/promise-spawn, npm-install-checks, npm-package-arg, npm-packlist, normalize-package-data, @npmcli/package-json, bin-links, nopt, npmlog, parse-conflict-json, dezalgo, read
1121+
- semver, ignore-walk, @npmcli/eslint-config, @npmcli/template-oss, npm-normalize-package-bin, @npmcli/name-from-folder, json-parse-even-better-errors, @npmcli/move-file, fs-minipass, infer-owner, ssri, unique-slug, hosted-git-info, proc-log, validate-npm-package-name, @npmcli/node-gyp, minipass-fetch, cmd-shim, read-cmd-shim, write-file-atomic, abbrev, are-we-there-yet, gauge, wrappy, treeverse, minify-registry-metadata, @npmcli/disparity-colors, @npmcli/ci-detect, mute-stream, ini, npm-audit-report, npm-user-validate

‎Makefile

Lines changed: 3 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -3,94 +3,9 @@ SHELL = bash
33

44
PUBLISHTAG = $(shell node scripts/publish-tag.js)
55

6-
# these docs have the @VERSION@ tag in them, so they have to be rebuilt
7-
# whenever the package.json is touched, in case the version changed.
8-
version_mandocs = $(shell grep -rl '@VERSION@' docs/content \
9-
|sed 's|.md|.1|g' \
10-
|sed 's|docs/content/commands/|man/man1/|g' )
11-
12-
cli_mandocs = $(shell find docs/content/commands -name '*.md' \
13-
|sed 's|.md|.1|g' \
14-
|sed 's|docs/content/commands/|man/man1/|g' )
15-
16-
files_mandocs = $(shell find docs/content/configuring-npm -name '*.md' \
17-
|sed 's|.md|.5|g' \
18-
|sed 's|docs/content/configuring-npm/|man/man5/|g' )
19-
20-
misc_mandocs = $(shell find docs/content/using-npm -name '*.md' \
21-
|sed 's|.md|.7|g' \
22-
|sed 's|docs/content/using-npm/|man/man7/|g' )
23-
24-
mandocs = $(cli_mandocs) $(files_mandocs) $(misc_mandocs)
25-
26-
markdown_docs = $(shell for file in $(find lib/commands -name '*.js'); do echo docs/content/commands/npm-$(basename $file .js).md; done)
27-
28-
all: docs
29-
30-
docs: mandocs htmldocs $(markdown_docs)
31-
32-
# don't regenerate the snapshot if we're generating
33-
# snapshots, since presumably we just did that.
34-
mandocs: deps $(mandocs)
35-
@ ! [ "$${npm_lifecycle_event}" = "snap" ] && \
36-
! [ "$${npm_lifecycle_event}" = "postsnap" ] && \
37-
TAP_SNAPSHOT=1 node test/lib/utils/config/definitions.js || true
38-
39-
$(version_mandocs): package.json
40-
41-
htmldocs: deps
42-
node bin/npm-cli.js rebuild cmark-gfm
43-
node docs/bin/dockhand.js
44-
45-
clean: docsclean gitclean
46-
47-
docsclean:
48-
rm -rf man
49-
506
deps:
517
node bin/npm-cli.js run resetdeps
528

53-
## targets for man files, these are encouraged to be only built by running `make docs` or `make mandocs`
54-
man/man1/%.1: docs/content/commands/%.md docs/bin/docs-build.js
55-
@[ -d man/man1 ] || mkdir -p man/man1
56-
node docs/bin/docs-build.js $< $@
57-
58-
man/man5/npm-json.5: man/man5/package.json.5
59-
cp $< $@
60-
61-
man/man5/npm-global.5: man/man5/folders.5
62-
cp $< $@
63-
64-
man/man5/%.5: docs/content/configuring-npm/%.md docs/bin/docs-build.js
65-
@[ -d man/man5 ] || mkdir -p man/man5
66-
node docs/bin/docs-build.js $< $@
67-
68-
man/man7/%.7: docs/content/using-npm/%.md docs/bin/docs-build.js
69-
@[ -d man/man7 ] || mkdir -p man/man7
70-
node docs/bin/docs-build.js $< $@
71-
72-
# Any time the config definitions description changes, automatically
73-
# update the documentation to account for it
74-
docs/content/using-npm/config.md: docs/bin/config-doc.js lib/utils/config/*.js
75-
node docs/bin/config-doc.js
76-
77-
mddocs: docs/bin/config-doc-command.js lib/utils/config/*.js lib/utils/cmd-list.js
78-
@for file in $(shell find docs/content/commands -name 'npm-*.md'); do \
79-
cmdname=$$(basename $$file .md) ;\
80-
cmdname=$${cmdname##npm-} ;\
81-
echo node docs/bin/config-doc-command.js $${file} lib/commands/$${cmdname}.js ;\
82-
node docs/bin/config-doc-command.js $${file} lib/commands/$${cmdname}.js ;\
83-
done
84-
85-
docs/content/commands/npm-%.md: lib/commands/%.js
86-
node docs/bin/config-doc-command.js $@ $<
87-
88-
freshdocs:
89-
touch lib/utils/config/definitions.js
90-
touch docs/bin/*.js
91-
make docs
92-
make mddocs
93-
949
lint-all: deps
9510
node bin/npm-cli.js run lint-all
9611

@@ -113,10 +28,10 @@ prune: deps
11328
node bin/npm-cli.js prune --omit=dev --no-save --no-audit --no-fund
11429
node scripts/git-dirty.js
11530

116-
publish: gitclean ls-ok link docs lint-all test-all prune
31+
publish: gitclean ls-ok link lint-all test-all prune
11732
node bin/npm-cli.js publish --tag=$(PUBLISHTAG)
11833

119-
release: gitclean ls-ok docs prune
34+
release: gitclean ls-ok prune
12035
@bash scripts/release.sh
12136

122-
.PHONY: all latest install dev link docs mddocs clean uninstall lint-all test-all man docsclean release ls-ok deps prune freshdocs
37+
.PHONY: link gitclean uninstall lint-all test-all release ls-ok deps prune

‎docs/.gitignore

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,12 +10,10 @@
1010
!/.gitignore
1111
!/bin/
1212
!/CHANGELOG*
13-
!/content/
1413
!/docs/
1514
!/lib/
1615
!/LICENSE*
1716
!/map.js
18-
!/nav.yml
1917
!/package.json
2018
!/README*
2119
!/scripts/

‎docs/bin/build.js

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
const run = require('../lib/build.js')
2+
const { paths } = require('../lib/index')
3+
4+
run({
5+
verify: true,
6+
...paths,
7+
})
8+
.then((res) => console.log(`Wrote ${res.length} files`))
9+
.catch((err) => {
10+
process.exitCode = 1
11+
console.error(err)
12+
})

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy