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: https://github.com/nodejs/node/pull/10958
Fixes: https://github.com/nodejs/node/issues/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>

doc/api/addons.md

@@ -1,5 +1,7 @@
 # C++ Addons
 
+<!--introduced_in=v0.10.0-->
+
 Node.js Addons are dynamically-linked shared objects, written in C++, that
 can be loaded into Node.js using the [`require()`][require] function, and used
 just as if they were an ordinary Node.js module. They are used primarily to

doc/api/assert.md

@@ -1,5 +1,7 @@
 # Assert
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 The `assert` module provides a simple set of assertion tests that can be used to

doc/api/buffer.md

@@ -1,5 +1,7 @@
 # Buffer
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 Prior to the introduction of [`TypedArray`] in ECMAScript 2015 (ES6), the

doc/api/child_process.md

@@ -1,5 +1,7 @@
 # Child Process
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 The `child_process` module provides the ability to spawn child processes in

doc/api/cli.md

@@ -1,5 +1,6 @@
 # Command Line Options
 
+<!--introduced_in=v5.9.1-->
 <!--type=misc-->
 
 Node.js comes with a variety of CLI options. These options expose built-in

doc/api/cluster.md

@@ -1,5 +1,7 @@
 # Cluster
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 A single instance of Node.js runs in a single thread. To take advantage of

doc/api/console.md

@@ -1,5 +1,7 @@
 # Console
 
+<!--introduced_in=v0.10.13-->
+
 > Stability: 2 - Stable
 
 The `console` module provides a simple debugging console that is similar to the

doc/api/crypto.md

@@ -1,5 +1,7 @@
 # Crypto
 
+<!--introduced_in=v0.3.6-->
+
 > Stability: 2 - Stable
 
 The `crypto` module provides cryptographic functionality that includes a set of

doc/api/debugger.md

@@ -1,5 +1,7 @@
 # Debugger
 
+<!--introduced_in=v0.9.12-->
+
 > Stability: 2 - Stable
 
 <!-- type=misc -->

doc/api/dgram.md

@@ -1,5 +1,7 @@
 # UDP / Datagram Sockets
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 <!-- name=dgram -->

doc/api/dns.md

@@ -1,5 +1,7 @@
 # DNS
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 The `dns` module contains functions belonging to two different categories:

doc/api/documentation.md

@@ -1,5 +1,6 @@
 # About this Documentation
 
+<!--introduced_in=v0.10.0-->
 <!-- type=misc -->
 
 The goal of this documentation is to comprehensively explain the Node.js

doc/api/domain.md

@@ -7,6 +7,8 @@ changes:
                  the first promise of a chain was created.
 -->
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 0 - Deprecated
 
 **This module is pending deprecation**. Once a replacement API has been

doc/api/errors.md

@@ -1,5 +1,6 @@
 # Errors
 
+<!--introduced_in=v4.0.0-->
 <!--type=misc-->
 
 Applications running in Node.js will generally experience four categories of

doc/api/events.md

@@ -1,5 +1,7 @@
 # Events
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 <!--type=module-->

doc/api/fs.md

@@ -1,5 +1,7 @@
 # File System
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 <!--name=fs-->

doc/api/globals.md

@@ -1,5 +1,6 @@
 # Global Objects
 
+<!--introduced_in=v0.10.0-->
 <!-- type=misc -->
 
 These objects are available in all modules. The following variables may appear

doc/api/http.md

@@ -1,5 +1,7 @@
 # HTTP
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 To use the HTTP server and client one must `require('http')`.

doc/api/https.md

@@ -1,5 +1,7 @@
 # HTTPS
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 HTTPS is the HTTP protocol over TLS/SSL. In Node.js this is implemented as a

doc/api/modules.md

@@ -1,5 +1,7 @@
 # Modules
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 <!--name=module-->

doc/api/net.md

@@ -1,5 +1,7 @@
 # Net
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 The `net` module provides an asynchronous network API for creating stream-based

doc/api/os.md

@@ -1,5 +1,7 @@
 # OS
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 The `os` module provides a number of operating system-related utility methods.

doc/api/path.md

@@ -1,5 +1,7 @@
 # Path
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 The `path` module provides utilities for working with file and directory paths.

doc/api/process.md

@@ -1,5 +1,6 @@
 # Process
 
+<!-- introduced_in=v0.10.0 -->
 <!-- type=global -->
 
 The `process` object is a `global` that provides information about, and control

doc/api/punycode.md

@@ -6,6 +6,8 @@ changes:
     description: Accessing this module will now emit a deprecation warning.
 -->
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 0 - Deprecated
 
 **The version of the punycode module bundled in Node.js is being deprecated**.

doc/api/querystring.md

@@ -1,5 +1,7 @@
 # Query String
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 <!--name=querystring-->

doc/api/readline.md

@@ -1,5 +1,7 @@
 # Readline
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 The `readline` module provides an interface for reading data from a [Readable][]

doc/api/repl.md

@@ -1,5 +1,7 @@
 # REPL
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 The `repl` module provides a Read-Eval-Print-Loop (REPL) implementation that

doc/api/stream.md

@@ -1,5 +1,7 @@
 # Stream
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 A stream is an abstract interface for working with streaming data in Node.js.

doc/api/string_decoder.md

@@ -1,5 +1,7 @@
 # String Decoder
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 The `string_decoder` module provides an API for decoding `Buffer` objects into

doc/api/synopsis.md

@@ -1,5 +1,6 @@
 # Usage
 
+<!--introduced_in=v0.10.0-->
 <!--type=misc-->
 
 `node [options] [v8 options] [script.js | -e "script" | - ] [arguments]`

doc/api/timers.md

@@ -1,5 +1,7 @@
 # Timers
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 The `timer` module exposes a global API for scheduling functions to

doc/api/tls.md

@@ -1,5 +1,7 @@
 # TLS (SSL)
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 The `tls` module provides an implementation of the Transport Layer Security

doc/api/tty.md

@@ -1,5 +1,7 @@
 # TTY
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 The `tty` module provides the `tty.ReadStream` and `tty.WriteStream` classes.

doc/api/url.md

@@ -1,5 +1,7 @@
 # URL
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 The `url` module provides utilities for URL resolution and parsing. It can be

doc/api/util.md

@@ -1,5 +1,7 @@
 # Util
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 The `util` module is primarily designed to support the needs of Node.js' own

doc/api/v8.md

@@ -1,5 +1,7 @@
 # V8
 
+<!--introduced_in=v4.0.0-->
+
 The `v8` module exposes APIs that are specific to the version of [V8][]
 built into the Node.js binary. It can be accessed using:
 

doc/api/vm.md

@@ -1,5 +1,7 @@
 # VM (Executing JavaScript)
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 <!--name=vm-->

doc/api/zlib.md

@@ -1,5 +1,7 @@
 # Zlib
 
+<!--introduced_in=v0.10.0-->
+
 > Stability: 2 - Stable
 
 The `zlib` module provides compression functionality implemented using Gzip and

doc/api_assets/style.css

@@ -81,6 +81,61 @@ em code {
 
 #gtoc {
   font-size: .8em;
+  margin-bottom: 1em;
+}
+
+#gtoc ul {
+  list-style: none;
+  margin-left: 0;
+}
+
+#gtoc li {
+  display: inline;
+}
+
+li.version-picker {
+  position: relative;
+}
+
+li.version-picker:hover > ol {
+  display: block;
+}
+
+li.version-picker a span {
+  font-size: .7em;
+}
+
+ol.version-picker {
+  background: #fff;
+  border: 1px #43853d solid;
+  border-radius: 2px;
+  display: none;
+  list-style: none;
+  position: absolute;
+  right: -2px;
+  width: 101%;
+}
+
+#gtoc ol.version-picker li {
+  display: block;
+}
+
+ol.version-picker li a {
+  border-radius: 0;
+  display: block;
+  margin: 0;
+  padding: .1em;
+  padding-left: 1em;
+}
+
+ol.version-picker li:first-child a {
+  border-top-right-radius: 1px;
+  border-top-left-radius: 1px;
+}
+
+ol.version-picker li:last-child a {
+  border-bottom-right-radius: 1px;
+  border-bottom-left-radius: 1px;
 }
 
 .line {
@@ -507,6 +562,9 @@ th > *:last-child, td > *:last-child {
   #content {
     font-size: 3.5em;
   }
+  #gtoc {
+    font-size: 0.6em;
+  }
 }
 
 @media print {

doc/template.html

@@ -23,11 +23,21 @@
       <header>
         <h1>Node.js __VERSION__ Documentation</h1>
         <div id="gtoc">
-          <p>
+          <ul>
+            <li>
               <a href="index.html" name="toc">Index</a> |
+            </li>
+            <li>
               <a href="all.html">View on single page</a> |
-            <a href="__FILENAME__.json">View as JSON</a>
+            </li>
-          </p>
+            <li>
+              <a href="__FILENAME__.json">View as JSON</a> |
+            </li>
+            <li class="version-picker">
+              <a href="#">View another version <span>&#x25bc;</span></a>
+              __ALTDOCS__
+            </li>
+          </ul>
         </div>
         <hr>
       </header>

tools/doc/html.js

@@ -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 = /<!--\s*introduced_in\s*=\s*v([0-9]+)\.([0-9]+)\.([0-9]+)\s*-->/;
 
 // customized heading without id attribute
 const renderer = new marked.Renderer();
@@ -52,13 +53,17 @@ const gtocPath = path.resolve(path.join(
 ));
 var gtocLoading = null;
 var gtocData = null;
+var docCreated = null;
+var nodeVersion = null;
 
 /**
  * opts: input, filename, template, nodeVersion.
  */
 function toHTML(opts, cb) {
   const template = opts.template;
-  const nodeVersion = opts.nodeVersion || process.version;
+
+  nodeVersion = opts.nodeVersion || process.version;
+  docCreated = opts.input.match(DOC_CREATED_REG_EXP);
 
   if (gtocData) {
     return onGtocLoaded();
@@ -157,6 +162,8 @@ function render(opts, cb) {
       );
     }
 
+    template = template.replace(/__ALTDOCS__/, altDocs(filename));
+
     // content has to be the last thing we do with
     // the lexed tokens, because it's destructive.
     const content = marked.parser(lexed);
@@ -188,6 +195,50 @@ function replaceInText(text) {
   return linkJsTypeDocs(linkManPages(text));
 }
 
+function altDocs(filename) {
+  let html = '';
+
+  if (!docCreated) {
+    console.error(`Failed to add alternative version links to ${filename}`);
+    return html;
+  }
+
+  function lte(v) {
+    const ns = v.num.split('.');
+    if (docCreated[1] > +ns[0])
+      return false;
+    if (docCreated[1] < +ns[0])
+      return true;
+    return docCreated[2] <= +ns[1];
+  }
+
+  const versions = [
+    { num: '8.x' },
+    { num: '7.x' },
+    { num: '6.x', lts: true },
+    { num: '5.x' },
+    { num: '4.x', lts: true },
+    { num: '0.12.x' },
+    { num: '0.10.x' }
+  ];
+
+  const host = 'https://nodejs.org';
+  const href = (v) => `${host}/docs/latest-v${v.num}/api/${filename}.html`;
+
+  function li(v, i) {
+    let html = `<li><a href="${href(v)}">${v.num}`;
+
+    if (v.lts)
+      html += ' <b>LTS</b>';
+
+    return html + '</a></li>';
+  }
+
+  const lis = (vs) => vs.filter(lte).map(li).join('\n');
+
+  return `<ol class="version-picker">${lis(versions)}</ol>`;
+}
+
 // handle general body-text replacements
 // for example, link man page references to the actual page
 function parseText(lexed) {