tools: simplify HTML generation
Checklist
-
make -j4 test
(UNIX), orvcbuild 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.
- Asynchronous loading of
doc/template.html
. - Asynchronous loading of
doc/api/_toc.md
. - 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:
-
tools/doc/html.js
is required intools/doc/generate.js
andtest/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 samedoc/template.html
is loaded needlessly. -
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
- 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 indoc/ap/_toc.md
so the requiring this module is excessiveness.
This PR try to eliminate all downsides in this way:
-
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. -
We can preload
doc/api/_toc.md
synchronously and delete a huge async machinery. -
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.