Skip to content

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

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

Closed
mhdawson wants to merge 7 commits into from
Closed

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

Changes from 1 commit
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
12 changes: 10 additions & 2 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
These artifacts 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
Makefile target as part of the release-sources part of the
[iojs+release job](https://github.com/nodejs/node/blob/1a83ad6a693f851199608ae957ac5d4f76871485/Makefile#L1218-L1224).
Copy link
Member

@ovflowd ovflowd Nov 25, 2022

Choose a reason for hiding this comment

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

Can we reference HEAD here?

Copy link
Member

@richardlau richardlau Nov 25, 2022

Choose a reason for hiding this comment

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

Not without losing the highlighting (the line numbers are specific to that revision of the makefile).

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
Copy link
Member

@ovflowd ovflowd Nov 25, 2022

Choose a reason for hiding this comment

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

Do we need to go that deep into the specifics here? Isn't that visible by reading the Makefile?

Copy link
Member Author

@mhdawson mhdawson Nov 28, 2022

Choose a reason for hiding this comment

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

I think the few lines are worth avoiding people having to click into the link.

`/home/staging/nodejs/<type>/<full_version>/docs` where <type> is e.g.
Copy link
Member

@richardlau richardlau Nov 25, 2022

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

@ovflowd ovflowd Nov 25, 2022

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

@mhdawson mhdawson Nov 28, 2022

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