Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: add detail on how api docs are published #45626

Closed
wants to merge 7 commits into from
Closed

doc: add detail on how api docs are published #45626

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
72c8ecf
doc: add detail on how api docs are published
mhdawson Nov 25, 2022
3b0ccd9
Update doc/contributing/api-documentation.md
mhdawson Nov 28, 2022
25368bb
Update doc/contributing/api-documentation.md
mhdawson Nov 28, 2022
af3b4fd
Update doc/contributing/api-documentation.md
mhdawson Nov 28, 2022
be34ef8
Update doc/contributing/api-documentation.md
mhdawson Nov 28, 2022
45aed40
Update doc/contributing/api-documentation.md
mhdawson Nov 28, 2022
19a67bd
fixued linter issues
mhdawson Dec 1, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 13 additions & 5 deletions doc/contributing/api-documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,21 @@ generate the following:
1. Human-readable HTML in `out/doc/api/*.html`
2. A JSON representation in `out/doc/api/*.json`

These are published to nodejs.org for multiple versions of Node.js. As an
example the latest version of the human-readable HTML is published to
[nodejs.org/en/doc](https://nodejs.org/en/docs/), and the latest version
of the json documentation is published to
These artifacts are published to nodejs.org for multiple versions of
Node.js. As an example the latest version of the human-readable HTML
is published to [nodejs.org/en/doc](https://nodejs.org/en/docs/),
and the latest version of the json documentation is published to
[nodejs.org/api/all.json](https://nodejs.org/api/all.json)

<!-- TODO: Add docs about how the publishing process happens -->
The artifacts are built as part of release builds by running the [doc-upload](/~https://github.com/nodejs/node/blob/1a83ad6a693f851199608ae957ac5d4f76871485/Makefile#L1218-L1224)
Makefile target as part of the release-sources part of the
iojs+release job.
This target runs the `doc` target to build the docs and then uses
`scp` to copy them onto the staging/www server into a directory of the form
`/home/staging/nodejs/<type>/<full_version>/docs` where <type> is e.g.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm undecided whether the details of where the files are on the server are useful here or not as it's only useful to people with root access to the server (e.g. the build-infra team).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's kinda what I meant, this kind of text feels like it should belong on nodejs/build?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we have this documented anywhere else and I don't think it's too much of a distraction so the value of having it documented somewhere easy to find is worth it.

release, nightly, etc. The promotion step (either automatic for
nightlies or manual for releases) then moves the docs to
`/home/dist/nodejs/docs/\<full\_version>` where they are served by node.org.

**The key things to know about the tooling include:**

Expand Down