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.

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 links to alternative versions of doc #10958

Closed
wants to merge 10 commits into
base: master
from

Conversation

@chris--young
Contributor

chris--young commented Jan 23, 2017

Each page of the api documentation should have links to other versions
of the same page. This will make it easier to switch between the current
"live" release at nodejs.org and LTS versions.

Fixes: #10726

screen shot 2017-05-09 at 3 24 36 pm

Checklist
  • make -j4 test (UNIX), or vcbuild test (Windows) passes
  • documentation is changed or added
  • commit message follows commit guidelines
Affected core subsystem(s)

doc, tools

@evanlucas

This comment has been minimized.

Member

evanlucas commented Jan 23, 2017

This is great @chris--young. Thanks for doing this.

tools/doc/html.js Outdated
const a = (v) => `<a href="${href(v)}">v${v}</a>`;
const as = (vs) => vs.filter(lte).map(a).join(' / ');
const lts = as(['0.12.x', '4.x', '6.x']);

This comment has been minimized.

@evanlucas

evanlucas Jan 23, 2017

Member

0.12 is no longer in maintenance mode, so I would say remove it from here.

This comment has been minimized.

@chris--young

chris--young Jan 24, 2017

Contributor

I've moved v0.12 into the "Unsupported" section

tools/doc/html.js Outdated
if (lts.length)
html += '<b>LTS:</b> ' + lts;
const unsupported = as(['0.10.x', '5.x', '7.x']);

This comment has been minimized.

@evanlucas

evanlucas Jan 23, 2017

Member

v7.x is still a supported version, so calling it Unsupported would be confusing IMO

This comment has been minimized.

@chris--young

chris--young Jan 24, 2017

Contributor

v7.x is now labeled as Current

@Trott

This comment has been minimized.

Member

Trott commented Jan 31, 2017

@evanlucas It looks like @chris--young has tried to address your comments. Can you PTAL when you get a chance and (if appropriate) update your review status?

@Trott

This comment has been minimized.

Member

Trott commented Jan 31, 2017

This could use some more reviewers. Looping in the people who gave it a +1 commented in the original issue: @MylesBorins @benjamingr @sam-github

Also: @nodejs/documentation

@sam-github

This comment has been minimized.

Member

sam-github commented Jan 31, 2017

I didn't give it a +1 in the original issue, at least I see no signs I did :-). I just CCed it to the website group.

The docs we have right now for 7.x are better to use for 4.x than than the 4.x docs were.

This is likely to misdirect people into thinking that node is like express, http://expressjs.com/en/4x/api.html, where you should always look at the docs for the version you are using.

I won't object if others find this useful, but I also won't approve.

@chris--young

This comment has been minimized.

Contributor

chris--young commented Feb 10, 2017

@sam-github any suggestions for how I can salvage this? I was thinking if I restyled the links it might be clearer that you're probably looking for the latest version (7.x) and that 0.10x - 6.x are older versions.

@sam-github

This comment has been minimized.

Member

sam-github commented Feb 10, 2017

@chris--young I'm +/- 0. You could try to convince me, then you'd have two approvals once you address @evanlucas 's comments :-). The PR says what it does, but doesn't say why ("I was thinking it'd be nice" doesn't count). What's the use-case?

@nodejs/documentation @nodejs/website PTAL

@Trott

This comment has been minimized.

Member

Trott commented Feb 10, 2017

What's the use-case?

I would think one use case is if some API was the subject of a breaking change in 7.x but you're using 4.x or 6.x, you'll want to switch to the earlier docs easily.

@sam-github

This comment has been minimized.

Member

sam-github commented Feb 10, 2017

Except you won't really know that was a breaking change, unless it was the intoduction or removal of an entire API (because we don't document major changes other than that). And many of the doc improvements apply to older releases. We'd have to start being really rigorous about backporting docs. Currently, the don't backport clean to 4.x because of the .markdown to .md rename, so 4.x docs are no longer the best reference for the features in 4.x. I guess I'm saying I don't think we maintain the LTS docs rigorously enough, and we don't break the node API very much, so this isn't as useful as http://expressjs.com/en/4x/api.html vs http://expressjs.com/en/3x/api.html, and it may be dangerous to suggest we do.

On the other hand, maybe this will force us to backport all doc improvements more consistently, which would be a good thing.

@toddself

This comment has been minimized.

Contributor

toddself commented Feb 26, 2017

I filed the original issue for this. @sam-github the idea isn't to be able to figure out what is different but to easily be able to find relevant documentation. Each major version is a major version specifically because something in an outward API changed. If i am writing code for 4.x (or even 6.x) I need to be able to quickly look up docs for that version. Right now this is hard - if you google something you always get latest. It should be trivial to get linked to the version of the docs for the API you are working with

The node 7 docs are not helpful when writing code for node 4 (or even node .12 if you are still supporting such a thing).

doc/api/addons.md Outdated
@@ -1,5 +1,7 @@
# Addons
<!--doc_created=v0.10.0-->

This comment has been minimized.

@thefourtheye

thefourtheye Feb 26, 2017

Contributor

doc sounds superfluous to me. How about "introduced_in"?

This comment has been minimized.

@chris--young

chris--young Mar 4, 2017

Contributor

@thefourtheye: seems reasonable, just made that change

@sam-github

This comment has been minimized.

Member

sam-github commented Feb 27, 2017

Each major version is a major version specifically because something in an outward API changed.

@toddself spelling corrections in the thrown Error messages are semver-major

OK, I don't object to this, it sounds easy and like some people will find it useful, but I should point out that when the documentation is improved on master, as it often is, for features going all the way back to before LTS (including docs of APIs that existed in 4.x but were not doced), that does NOT guarantee that the docs get backported.

@chris--young

This comment has been minimized.

Contributor

chris--young commented Mar 8, 2017

@evanlucas please re-review

doc/api/crypto.md Outdated
@@ -1,5 +1,7 @@
# Crypto
<!--introduced_in=v0.10.0-->

This comment has been minimized.

@evanlucas

evanlucas Mar 9, 2017

Member

I don't believe this is correct. (https://nodejs.org/docs/v0.3.6/api/crypto.html) crypto has been around for a while. https://nodejs.org/en/download/releases/ is a useful page to check :]

This comment has been minimized.

@chris--young

chris--young Mar 9, 2017

Contributor

Oh cool, I had only been looking at https://nodejs.org/dist/ and must have messed up a few versions. I'll go back over all the docs and make sure these tags are the right version number.

doc/api/debugger.md Outdated
@@ -1,5 +1,7 @@
# Debugger
<!--introduced_in=v0.10.0-->

This comment has been minimized.

@evanlucas

evanlucas Mar 9, 2017

Member

I don't think this is correct either? https://nodejs.org/dist/v0.9.12/docs/api/debugger.html

tools/doc/html.js Outdated
const a = (v) => `<a href="${href(v)}">v${v}</a>`;
const as = (vs) => vs.filter(lte).map(a).join(' / ');
html += 'View another version of this page <b>Current:</b> ' + a('7.x');

This comment has been minimized.

@evanlucas

evanlucas Mar 9, 2017

Member

so one concern I have here is what will this look like when Node 8 is released? It will be released as a "Current" release line for a while before going LTS. With that, there will be a few months of layover where Node 7 is still also a "Current" release.

@tinder-ydong

This comment has been minimized.

tinder-ydong commented May 9, 2017

had same problem finding different versions of docs, and feel it'd be really convenient to add links to different versions

@Trott

This comment has been minimized.

Member

Trott commented Jul 16, 2017

@chris--young Are you able to rebase this to get rid of the conflicts? I'd like to renew the effort to get this landed.

Chris Young added some commits Jan 23, 2017

doc: add links to alternative versions of doc
Each page of the api documentation should have links to other versions
of the same page. This will make it easier to switch between the current
"live" release at nodejs.org and LTS versions.

Fixes: #10726
doc: fixes version labeling of alt doc links
v0.12.x is no longer LTS, and v7.x should not be labeled as
"unsupported"

Fixes: #10726
@chris--young

This comment has been minimized.

Contributor

chris--young commented Jul 24, 2017

Cool, seems like most people prefer this approach so I'll take another pass to clean up the styling a and code some more.

@BridgeAR

This looks good and I think it could be merged right away besides the nit @aqrln pointed out.

@chris--young you said you wanted to have another look at the style for mobile. I think this could actually be done in a separate PR. What do you think?

@chris--young

This comment has been minimized.

Contributor

chris--young commented Aug 26, 2017

@BridgeAR I don't really like the idea of merging it when we know it's broken on mobile. If you can give me till the end of the weekend i'll get it to where it needs to be.

Node.js Addons are dynamically-linked shared objects, written in C++, that
<!--introduced_in=v0.10.0-->
Node.js Addons are dynamically-linked shared objects, written in C or C++, that

This comment has been minimized.

@thefourtheye

thefourtheye Aug 26, 2017

Contributor

This commit explicitly changed this to C++ abfd4bf

@@ -31,6 +31,7 @@ const typeParser = require('./type-parser.js');
module.exports = toHTML;
const STABILITY_TEXT_REG_EXP = /(.*:)\s*(\d)([\s\S]*)/;
const DOC_CREATED_REG_EXP = /<!--introduced_in=v([0-9]+).([0-9]+).([0-9]+)-->/;

This comment has been minimized.

@thefourtheye

thefourtheye Aug 26, 2017

Contributor

The dots need to be escaped. Also, you can optionally relax the RegEx to accept optional spaces.

return html;
}
function lte(v) {

This comment has been minimized.

@thefourtheye

thefourtheye Aug 26, 2017

Contributor

String based comparison with v.num is not good enough. Why not split it at dots and the do integer comparison?

let html = '';
if (!docCreated) {
console.error('Failed to add alternative version links');

This comment has been minimized.

@thefourtheye

thefourtheye Aug 26, 2017

Contributor

Nit: If the filename is also included, it would help in debugging.

@@ -31,6 +31,7 @@ const typeParser = require('./type-parser.js');
module.exports = toHTML;
const STABILITY_TEXT_REG_EXP = /(.*:)\s*(\d)([\s\S]*)/;
const DOC_CREATED_REG_EXP = /<!--introduced_in( )?=( )?v([0-9]+)\.([0-9]+)\.([0-9]+)-->/;

This comment has been minimized.

@thefourtheye

thefourtheye Aug 26, 2017

Contributor

I was thinking more like

const DOC_CREATED_REG_EXP = /<!--\s*introduced_in\s*=\s*v([0-9]+)\.([0-9]+)\.([0-9]+)\s*-->/;
{ num: '5.x' },
{ num: '4.x', lts: true },
{ num: '0.12.x' },
{ num: '0.10.x' },

This comment has been minimized.

@thefourtheye

thefourtheye Aug 26, 2017

Contributor

Nit: Extra comma at the end.

@chris--young

This comment has been minimized.

Contributor

chris--young commented Aug 28, 2017

@BridgeAR should be good to go now, unless anyone has objections

tniessen added a commit to tniessen/node that referenced this pull request Aug 28, 2017

doc: add links to alternative versions of doc
Each page of the API documentation should have links to other versions
of the same page. This will make it easier to switch between the current
"live" release at nodejs.org and LTS versions.

PR-URL: nodejs#10958
Fixes: nodejs#10726
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
@tniessen

This comment has been minimized.

Member

tniessen commented Aug 28, 2017

Landed in cacce30, thank you for the contribution! 🎉

@tniessen tniessen closed this Aug 28, 2017

@targos

This comment has been minimized.

Member

targos commented Aug 28, 2017

A little linting error was introduced with this commit. Fix: #15063

oe added a commit to ayojs/ayo that referenced this pull request Aug 30, 2017

doc: add links to alternative versions of doc
Each page of the API documentation should have links to other versions
of the same page. This will make it easier to switch between the current
"live" release at nodejs.org and LTS versions.

PR-URL: nodejs/node#10958
Fixes: nodejs/node#10726
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

oe added a commit to ayojs/ayo that referenced this pull request Aug 30, 2017

doc: add links to alternative versions of doc
Each page of the API documentation should have links to other versions
of the same page. This will make it easier to switch between the current
"live" release at nodejs.org and LTS versions.

PR-URL: nodejs/node#10958
Fixes: nodejs/node#10726
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

cjihrig added a commit to cjihrig/node-1 that referenced this pull request Aug 31, 2017

doc: add links to alternative versions of doc
Each page of the API documentation should have links to other versions
of the same page. This will make it easier to switch between the current
"live" release at nodejs.org and LTS versions.

PR-URL: nodejs#10958
Fixes: nodejs#10726
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

MylesBorins added a commit that referenced this pull request Sep 10, 2017

doc: add links to alternative versions of doc
Each page of the API documentation should have links to other versions
of the same page. This will make it easier to switch between the current
"live" release at nodejs.org and LTS versions.

PR-URL: #10958
Fixes: #10726
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

@MylesBorins MylesBorins referenced this pull request Sep 10, 2017

Merged

v8.5.0 proposal #15308

MylesBorins added a commit that referenced this pull request Sep 12, 2017

doc: add links to alternative versions of doc
Each page of the API documentation should have links to other versions
of the same page. This will make it easier to switch between the current
"live" release at nodejs.org and LTS versions.

PR-URL: #10958
Fixes: #10726
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
@MylesBorins

This comment has been minimized.

Member

MylesBorins commented Sep 20, 2017

Should this be backported to v6.x-staging? If yes please follow the guide and raise a backport PR, if no let me know or add the dont-land-on label.

@refack

This comment has been minimized.

Member

refack commented Sep 20, 2017

@chris--young IMHO it would be nice to have this in 6 so as to enable cross referencing.
(Should be backported with the relevant fixes #15063, and #15420)

@chris--young

This comment has been minimized.

Contributor

chris--young commented Sep 20, 2017

@MylesBorins yea seems like a good idea. will open a pr soon

chris--young added a commit to chris--young/node that referenced this pull request Sep 29, 2017

doc: add links to alternative versions of doc
Each page of the API documentation should have links to other versions
of the same page. This will make it easier to switch between the current
"live" release at nodejs.org and LTS versions.

PR-URL: nodejs#10958
Fixes: nodejs#10726
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

MylesBorins added a commit that referenced this pull request Sep 29, 2017

doc: add links to alternative versions of doc
Each page of the API documentation should have links to other versions
of the same page. This will make it easier to switch between the current
"live" release at nodejs.org and LTS versions.

Backport-PR-URL: #15670
PR-URL: #10958
Fixes: #10726
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

@MylesBorins MylesBorins referenced this pull request Sep 29, 2017

Merged

v6.11.4 proposal #15506

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment