Skip to content

tools: simplify HTML generation

Checklist
  • make -j4 test (UNIX), or vcbuild test (Windows) passes
  • commit message follows commit guidelines

In tools/doc/html.js we have 3 operations that have little benefit but complicate the file significantly.

  1. Asynchronous loading of doc/template.html.
  2. Asynchronous loading of doc/api/_toc.md.
  3. Requiring tools/doc/preprocess.js and calling its main function.

While doing 1 and 2 asynchronously can have a performance benefit, it is rather small (both files are ~1.5 KB). Besides, the downsides are significant:

  1. tools/doc/html.js is required in tools/doc/generate.js and test/doctool/test-doctool-html.js. While the first script calls the main function once per requiring, the second script calls it many times and all these times the same doc/template.html is loaded needlessly.

  2. Asynchronous loading of doc/ap/_toc.md makes the script overcomplicated to the extent of this comment:

https://github.com/nodejs/node/blob/2a30bfe295eadbdaea3675447b9fe743c622b47b/tools/doc/html.js#L45

  1. The main aim of the tools/doc/preprocess.js is processing @include instructions. Also, as one goes, it strips special comments. There are no @include instructions in doc/ap/_toc.md so the requiring this module is excessiveness.

This PR try to eliminate all downsides in this way:

  1. As we have only one HTML template, we can exclude it as an option from cli chain, incorporate its path in tools/doc/html.js and preload it synchronously once per module initialization.

  2. We can preload doc/api/_toc.md synchronously and delete a huge async machinery.

  3. We can replace tools/doc/preprocess.js requiring with one-liner comment stripping in place.

This PR reduces the code almost by 50 lines producing the same result.

Please, ignore any remaining stylistic issues while reviewing the changes: I am going to modernize and optimize the whole script after this PR. This change is singled out to not mingle logic refactoring with many small changes scattering over the file.

Merge request reports

Loading