Skip to content

Commit 1125165

Browse files
authored
Generate CLI docs as a Docusaurus plugin (#6218)
**What's the problem this PR addresses?** The current method of CLI docs generation is very inefficient because it is synchronously blocking and memory-intensive. It can easily take up 40% of the time needed to start the dev server. **How did you fix it?** Created a Docusaurus plugin that generates the CLI docs. This has a number of advantages over the existing method: - It is async and happens in parallel to other Docusaurus plugins, thus much faster in terms of total build time. - It is written in TypeScript, so type-checked and has better DX - It obtains the command definitions by running the TypeScript source directly instead of going through a shell, saving overhead - It writes the result to disk via Docusaurus APIs, saving memory ### Performance ``` # Before Warm dev startup Time (mean ± σ): 68.887 s ± 1.508 s [User: 114.795 s, System: 18.496 s] Range (min … max): 67.447 s … 71.328 s 5 runs Cold dev startup Time (mean ± σ): 68.346 s ± 0.204 s [User: 104.264 s, System: 15.938 s] Range (min … max): 68.195 s … 68.675 s 5 runs Warm Build Time (mean ± σ): 110.748 s ± 0.781 s [User: 139.832 s, System: 15.310 s] Range (min … max): 109.902 s … 111.528 s 5 runs Cold Build Time (mean ± σ): 306.749 s ± 10.032 s [User: 1588.512 s, System: 300.103 s] Range (min … max): 298.550 s … 322.576 s 5 runs # After Warm dev startup Time (mean ± σ): 42.410 s ± 0.546 s [User: 60.527 s, System: 6.049 s] Range (min … max): 41.807 s … 43.265 s 5 runs Cold dev startup Time (mean ± σ): 42.275 s ± 0.326 s [User: 59.571 s, System: 5.824 s] Range (min … max): 41.760 s … 42.657 s 5 runs Warm Build Time (mean ± σ): 85.861 s ± 2.109 s [User: 95.237 s, System: 5.144 s] Range (min … max): 83.617 s … 88.499 s 5 runs Cold Build Time (mean ± σ): 149.498 s ± 7.973 s [User: 440.898 s, System: 15.700 s] Range (min … max): 140.074 s … 160.208 s 5 runs ``` ### Index pages I have also taken the opportunity to take the `@yarnpkg/cli` index page and adapted it to the other binaries ### ⚠️ URL changes Unfortunately, generating the CLI docs as a separate plugin makes the original URL scheme conflict with the main docs plugin, so we either have to - move all generated CLI docs under a single path prefix (e.g. `/cli`) - lose state (in particular, sidebar scroll state) when navigating between pages for different binaries I have opted to move everything under `/cli` ### Other Changes The change causes a few visual changes to existing stuff: - The previous page and next page links have been removed. Should be easy to recreate but I don't feel like they have much value - The sidebar is now sorted in lexicographical order - The additional binaries' examples now include the `yarn` invocation, and thus is properly styled - Very minor, but the column widths in the options table have shifted very slightly ### Future work This PR is ready, but I am still experimenting with a few things that may or may not make it into the PR. - <s>I'm trying whether it is possible to use Docusaurus's watch mechanism to hot rebuild the pages.</s> - <s>Also, as you can see, there are practically no difference in warm and cold startup time. Maybe checking mtimes can avoid some work?</s> **Checklist** <!--- Don't worry if you miss something, chores are automatically tested. --> <!--- This checklist exists to help you remember doing the chores when you submit a PR. --> <!--- Put an `x` in all the boxes that apply. --> - [x] I have read the [Contributing Guide](https://yarnpkg.com/advanced/contributing). <!-- See https://yarnpkg.com/advanced/contributing#preparing-your-pr-to-be-released for more details. --> <!-- Check with `yarn version check` and fix with `yarn version check -i` --> - [x] I have set the packages that need to be released for my changes to be effective. <!-- The "Testing chores" workflow validates that your PR follows our guidelines. --> <!-- If it doesn't pass, click on it to see details as to what your PR might be missing. --> - [x] I will check that all automated PR checks pass before the PR gets reviewed.
1 parent 1852e3e commit 1125165

File tree

13 files changed

+429
-233
lines changed

13 files changed

+429
-233
lines changed

.pnp.cjs

+4-2
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

.yarn/versions/9f4940a4.yml

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
releases:
2+
"@yarnpkg/builder": patch
3+
"@yarnpkg/pnpify": patch
4+
"@yarnpkg/sdks": patch
5+
6+
declined:
7+
- "@yarnpkg/plugin-constraints"
8+
- "@yarnpkg/plugin-exec"
9+
- "@yarnpkg/plugin-interactive-tools"
10+
- "@yarnpkg/plugin-stage"
11+
- "@yarnpkg/plugin-typescript"
12+
- "@yarnpkg/plugin-version"
13+
- "@yarnpkg/plugin-workspace-tools"
14+
- "@yarnpkg/cli"

0 commit comments

Comments
 (0)