1. Move the apilinks.json file into out/doc so it gets cleaned when
running `make docclean`
2. When the apilinks.json generated is empty, throw a specific error
so it's easier to understand what's wrong
3. Write to a file passed through CLI arguments instead writing to
stdout in apilinks.js so the build process is more robust in
the case of a bad binary
PR-URL: https://github.com/nodejs/node/pull/25019
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
The processing of strings like `8.x` into a major version number and a
minor version number results in minor versions that are `NaN`. In that
situation, since the picker will link to the latest docs in the
major version, include the version in the version picker.
Fixes: https://github.com/nodejs/node/issues/23979
PR-URL: https://github.com/nodejs/node/pull/24638
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
The Google Analytics tracking wasn't wholly uncontroversial and hasn't
been used in practice. Remove it.
PR-URL: https://github.com/nodejs/node/pull/23083
Fixes: https://github.com/nodejs/node/issues/22652
Refs: https://github.com/nodejs/node/pull/6601
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Roman Reiss <me@silverwind.io>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Parse source code using acorn; extracting exports. When producing
documentation, match exports to headers. When a match is found, add a [src]
link.
This first commit handles simple exported classes and functions, and does so
without requiring any changes to the source code or markdown. Subsequent
commits will attempt to match more headers, and some of these changes are
likely to require changes to the source code and/or markdown.
PR-URL: https://github.com/nodejs/node/pull/22405
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Notes:
1) Removed a number of root properties that did not seem relevant:
source, desc, and introduced_in. There no longer is a source, and
the other two are from the first include and do not reflect the
entire API.
2) As with https://github.com/nodejs/node/issues/20100, the current
"desc" properties sometimes contained in-page links, other times
referenced another page, and often did not match the links in the
original HTML or JSON file. I chose to standardize on external links
as "desc" values are isolated snippets as opposed to all.html which
can be viewed as a standalone and self contained document.
3) Eliminated preprocessing for @include entirely, including the test
case for this function.
4) _toc.md was renamed to index.md.
5) index comments no longer appear in embedded TOCs (left hand side
column in the generated documentation.
PR-URL: https://github.com/nodejs/node/pull/21637
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/20785
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
This PR reduces code by 40 lines and docs size by ~7.5 KB. Only
<div class="signature">...</div> wrappers are removed from docs,
no other changes are found in results.
PR-URL: https://github.com/nodejs/node/pull/20514
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
In preparation for a linting rule, use consistent quotation for
properties in objects.
PR-URL: https://github.com/nodejs/node/pull/19156
Reviewed-By: Gus Caplan <me@gus.host>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Teddy Katz <teddy.katz@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Roman Reiss <me@silverwind.io>
This is required because we need to add the babel-eslint dependency
and it has to be able to resolve "eslint".
babel-eslint is required to support future ES features such as async
iterators and import.meta.
Refs: https://github.com/nodejs/node/pull/17755
PR-URL: https://github.com/nodejs/node/pull/17820
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
common.projectDir is used in one test, so it's not so common. Remove
from common module to the one test file that needs it.
PR-URL: https://github.com/nodejs/node/pull/17781
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Timothy Gu <timothygu99@gmail.com>
Reviewed-By: Jon Moss <me@jonathanmoss.me>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
`test-make-doc` fails in CI on Raspberry Pi devices where `test-ci-js`
runs the test but does not build the docs. We do not want to build the
docs in these cases. Move the test to the `doctool` suite and add that
suite to `IGNORED_SUITES` in `test.py`. Specify `doctool` as a test
suite to run with `make test` or `make test-ci` but not with the
`make test-ci-js` job run on cross-compiled fanned CI tests like we do
with Raspberry Pi devices in CI.
PR-URL: https://github.com/nodejs/node/pull/16301
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Anatoli Papirovski <apapirovski@mac.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/13852
Refs: https://github.com/nodejs/node/issues/12586
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
* Remove needless RegExp flag
In fixed case, `/g` flag is needless in the boolean context.
* Remove needless RegExp capturing
Use non-capturing grouping or remove capturing completely when:
* capturing is useless per se, e.g. in test() check;
* captured groups are not used afterward at all;
* some of the later captured groups are not used afterward.
* Use test, not match/exec in boolean context
match() and exec() return a complicated object,
unneeded in a boolean context.
* Do not needlessly repeat RegExp creation
This commit takes RegExp creation out of cycles and other repetitions.
As long as the RegExp does not use /g flag and match indices,
we are safe here.
In tests, this fix hardly gives a significant performance gain,
but it increases clarity and maintainability,
reassuring some RegExps to be identical.
RegExp in functions are not taken out of their functions:
while these functions are called many times
and their RegExps are recreated with each call,
the performance gain in test cases
does not seem to be worth decreasing function self-dependency.
PR-URL: https://github.com/nodejs/node/pull/13770
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/11489
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Reviewed-By: Roman Reiss <me@silverwind.io>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Italo A. Casas <me@italoacasas.com>
Adds Google Analytics tracking script to all doc pages when
`DOCS_ANALYTICS` is set when running `make`:
```bash
$ DOCS_ANALYTICS=<GOOGLE ANALYTICS ID> make
```
By default (when `DOCS_ANALYTICS` is not set), no tracking scripts are
included.
It respects "Do Not Track" settings end users might have in their
browser.
Also changes make target `doc-upload` from depending on the
`$(TARBALL)` target, to only depend on `doc` directly.
PR-URL: https://github.com/nodejs/node/pull/6601
Reviewed-By: Johan Bergström <bugs@bergstroem.nu>
Reviewed-By: Rod Vagg <rod@vagg.org>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/10696
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
PR-URL: https://github.com/nodejs/node/pull/10541
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Italo A. Casas <me@italoacasas.com>
Previously, output files which were created using includes (notably,
the single-page all.html) had basically broken internal links all
over the place because references like `errors.html#errors_class_error`
are being used, yet `id` attributes were generated that looked like
`all_class_error`.
This PR adds generation of comments from the include preprocessor
that indicate from which file the current markdown bits come and
lets the HTML output generation take advantage of that so that more
appropriate `id` attributes can be generated.
PR-URL: https://github.com/nodejs/node/pull/6943
Reviewed-By: Robert Jefe Lindstaedt <robert.lindstaedt@gmail.com>
Reviewed-By: Daniel Wang <wangyang0123@gmail.com>
These signatures were originally converted to opts hashes in #3888. That
change was misinterpreted as the intrinsic cause of a test failure and
reverted in #6680.
PR-URL: https://github.com/nodejs/node/pull/6690
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Robert Jefe Lindstaedt <robert.lindstaedt@gmail.com>
Adjust style in doctool tests to conform with predominant style of the
rest of the project. The biggest changes are:
* Replace string concatenation with `path.join()`
* Remove unnecessary quotes from property names
PR-URL: https://github.com/nodejs/node/pull/6719
Reviewed-By: James M Snell <jasnell@gmail.com>
There has been occasional nits for spacing in object literals in PRs but
the project does not lint for it and it is not always handled
consistently in the existing code, even on adjacent lines of a file.
This change enables a linting rule requiring no space between the key
and the colon, and requiring at least one space (but allowing for more
so property values can be lined up if desired) between the colon and the
value. This appears to be the most common style used in the current code
base.
Example code the complies with lint rule:
myObj = { foo: 'bar' };
Examples that do not comply with the lint rule:
myObj = { foo : 'bar' };
myObj = { foo:'bar' };
PR-URL: https://github.com/nodejs/node/pull/6592
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Brian White <mscdex@mscdex.net>
Update module marked. Customize renderer to remove id from heading.
PR-URL: https://github.com/nodejs/node/pull/6396
Reviewed-By: Roman Reiss <me@silverwind.io>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Allow multiple `added:` version entries, since semver-minors
can trickle down to previous major versions, and thus
features may have been added in multiple versions.
Also include `deprecated:` entries and apply the same logic
to them for consistency.
Stylize the added HTML as `Added in:` and `Deprecated since:`.
PR-URL: https://github.com/nodejs/node/pull/6495
Reviewed-By: Robert Jefe Lindstaedt <robert.lindstaedt@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Add checks that make sure the doctool parses metadata correctly.
PR-URL: https://github.com/nodejs/node/pull/6495
Reviewed-By: Robert Jefe Lindstaedt <robert.lindstaedt@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
* Test the toHTML function in html.js. Check that given valid markdown
it produces the expected html. One test case will prevent regressions
of #5873.
* Check that when given valid markdown toJSON produces valid JSON with
the expected schema.
* Add doctool to the list of built in tests so it runs in CI.
PR-URL: https://github.com/nodejs/node/pull/6031
Fixes: https://github.com/nodejs/node/issues/5955
Reviewed-By: Roman Reiss <me@silverwind.io>
Reviewed-By: Rich Trott <rtrott@gmail.com>
