From ecea33b27745b20d8ab28642be4114a14f329329 Mon Sep 17 00:00:00 2001 From: Chris Young Date: Sun, 22 Jan 2017 19:16:21 -0800 Subject: [PATCH] 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: https://github.com/nodejs/node/pull/15670 PR-URL: https://github.com/nodejs/node/pull/10958 Fixes: https://github.com/nodejs/node/issues/10726 Reviewed-By: Refael Ackermann Reviewed-By: Evan Lucas Reviewed-By: Sakthipriyan Vairamani Reviewed-By: Ruben Bridgewater --- doc/api/addons.md | 2 ++ doc/api/assert.md | 2 ++ doc/api/buffer.md | 2 ++ doc/api/child_process.md | 2 ++ doc/api/cli.md | 1 + doc/api/cluster.md | 2 ++ doc/api/console.md | 2 ++ doc/api/crypto.md | 2 ++ doc/api/debugger.md | 2 ++ doc/api/dgram.md | 2 ++ doc/api/dns.md | 2 ++ doc/api/documentation.md | 1 + doc/api/domain.md | 2 ++ doc/api/errors.md | 1 + doc/api/events.md | 2 ++ doc/api/fs.md | 2 ++ doc/api/globals.md | 1 + doc/api/http.md | 2 ++ doc/api/https.md | 2 ++ doc/api/modules.md | 2 ++ doc/api/net.md | 2 ++ doc/api/os.md | 2 ++ doc/api/path.md | 2 ++ doc/api/process.md | 1 + doc/api/punycode.md | 2 ++ doc/api/querystring.md | 2 ++ doc/api/readline.md | 2 ++ doc/api/repl.md | 2 ++ doc/api/stream.md | 2 ++ doc/api/string_decoder.md | 2 ++ doc/api/synopsis.md | 1 + doc/api/timers.md | 2 ++ doc/api/tls.md | 2 ++ doc/api/tty.md | 2 ++ doc/api/url.md | 2 ++ doc/api/util.md | 2 ++ doc/api/v8.md | 2 ++ doc/api/vm.md | 2 ++ doc/api/zlib.md | 2 ++ doc/api_assets/style.css | 58 +++++++++++++++++++++++++++++++++++++++ doc/template.html | 20 ++++++++++---- tools/doc/html.js | 51 ++++++++++++++++++++++++++++++++++ 42 files changed, 196 insertions(+), 5 deletions(-) diff --git a/doc/api/addons.md b/doc/api/addons.md index 09049e3dbd8477..b17c1c9e5c51c7 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -1,5 +1,7 @@ # C/C++ Addons + + Node.js Addons are dynamically-linked shared objects, written in C or 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 diff --git a/doc/api/assert.md b/doc/api/assert.md index 6628a6b71df364..a0eb8d7a4a188e 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -1,5 +1,7 @@ # Assert + + > Stability: 2 - Stable The `assert` module provides a simple set of assertion tests that can be used to diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 1f8e8b5becef62..eb2447f4cfff04 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -1,5 +1,7 @@ # Buffer + + > Stability: 2 - Stable Prior to the introduction of [`TypedArray`] in ECMAScript 2015 (ES6), the diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 6bea59ebac3f12..d04f756eb7f140 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -1,5 +1,7 @@ # Child Process + + > Stability: 2 - Stable The `child_process` module provides the ability to spawn child processes in diff --git a/doc/api/cli.md b/doc/api/cli.md index 52ad3b324cc492..650e0cdbdb607e 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -1,5 +1,6 @@ # Command Line Options + Node.js comes with a variety of CLI options. These options expose built-in diff --git a/doc/api/cluster.md b/doc/api/cluster.md index 1d605503848963..a846ef0b55d2a0 100644 --- a/doc/api/cluster.md +++ b/doc/api/cluster.md @@ -1,5 +1,7 @@ # Cluster + + > Stability: 2 - Stable A single instance of Node.js runs in a single thread. To take advantage of diff --git a/doc/api/console.md b/doc/api/console.md index f3652a56561316..93ac3bd81ea4de 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -1,5 +1,7 @@ # Console + + > Stability: 2 - Stable The `console` module provides a simple debugging console that is similar to the diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 79c7a3c733e90a..7d94ffd6c77f72 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -1,5 +1,7 @@ # Crypto + + > Stability: 2 - Stable The `crypto` module provides cryptographic functionality that includes a set of diff --git a/doc/api/debugger.md b/doc/api/debugger.md index 1c9b1049e82491..a24437021b7bea 100644 --- a/doc/api/debugger.md +++ b/doc/api/debugger.md @@ -1,5 +1,7 @@ # Debugger + + > Stability: 2 - Stable diff --git a/doc/api/dgram.md b/doc/api/dgram.md index 2aec4abb254643..73e86baa0e175d 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -1,5 +1,7 @@ # UDP / Datagram Sockets + + > Stability: 2 - Stable diff --git a/doc/api/dns.md b/doc/api/dns.md index 457559d0ce692c..0a34f6efa8052d 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -1,5 +1,7 @@ # DNS + + > Stability: 2 - Stable The `dns` module contains functions belonging to two different categories: diff --git a/doc/api/documentation.md b/doc/api/documentation.md index f4b0c876c057c1..8109206ae2f055 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -1,5 +1,6 @@ # About this Documentation + The goal of this documentation is to comprehensively explain the Node.js diff --git a/doc/api/domain.md b/doc/api/domain.md index e98ccc87a0e346..08d6edc7d8cb24 100644 --- a/doc/api/domain.md +++ b/doc/api/domain.md @@ -1,5 +1,7 @@ # Domain + + > Stability: 0 - Deprecated **This module is pending deprecation**. Once a replacement API has been diff --git a/doc/api/errors.md b/doc/api/errors.md index 10a930ddd73c4b..49b4bac595a6dc 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -1,5 +1,6 @@ # Errors + Applications running in Node.js will generally experience four categories of diff --git a/doc/api/events.md b/doc/api/events.md index 7462902e09479a..1cffb5e2d5855f 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -1,5 +1,7 @@ # Events + + > Stability: 2 - Stable diff --git a/doc/api/fs.md b/doc/api/fs.md index 3f0a0f133070f2..7e446f28dcd6e4 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -1,5 +1,7 @@ # File System + + > Stability: 2 - Stable diff --git a/doc/api/globals.md b/doc/api/globals.md index b0467cdacde3a5..054bc2300bd411 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -1,5 +1,6 @@ # Global Objects + These objects are available in all modules. Some of these objects aren't diff --git a/doc/api/http.md b/doc/api/http.md index eab2e2721bd60b..2f087d39b36767 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -1,5 +1,7 @@ # HTTP + + > Stability: 2 - Stable To use the HTTP server and client one must `require('http')`. diff --git a/doc/api/https.md b/doc/api/https.md index ea99d8bcdb99b0..6f2a385b270434 100644 --- a/doc/api/https.md +++ b/doc/api/https.md @@ -1,5 +1,7 @@ # HTTPS + + > Stability: 2 - Stable HTTPS is the HTTP protocol over TLS/SSL. In Node.js this is implemented as a diff --git a/doc/api/modules.md b/doc/api/modules.md index 480f9e10ea57be..7e89a94924ba48 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -1,5 +1,7 @@ # Modules + + > Stability: 2 - Stable diff --git a/doc/api/net.md b/doc/api/net.md index 5a566dc7cb89c8..3308fc27f0edef 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -1,5 +1,7 @@ # Net + + > Stability: 2 - Stable The `net` module provides you with an asynchronous network wrapper. It contains diff --git a/doc/api/os.md b/doc/api/os.md index e13e3ae4217dd3..3dc2561ad72626 100644 --- a/doc/api/os.md +++ b/doc/api/os.md @@ -1,5 +1,7 @@ # OS + + > Stability: 2 - Stable The `os` module provides a number of operating system-related utility methods. diff --git a/doc/api/path.md b/doc/api/path.md index dfe68f1d3cfcb6..807cf9b88c9869 100644 --- a/doc/api/path.md +++ b/doc/api/path.md @@ -1,5 +1,7 @@ # Path + + > Stability: 2 - Stable The `path` module provides utilities for working with file and directory paths. diff --git a/doc/api/process.md b/doc/api/process.md index 0e8c17af7e605c..885569a4ad48f6 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -1,5 +1,6 @@ # Process + The `process` object is a `global` that provides information about, and control diff --git a/doc/api/punycode.md b/doc/api/punycode.md index 87d1c7d80ad431..f1aedc0cb86cc6 100644 --- a/doc/api/punycode.md +++ b/doc/api/punycode.md @@ -1,5 +1,7 @@ # Punycode + + > Stability: 0 - Deprecated **The version of the punycode module bundled in Node.js is being deprecated**. diff --git a/doc/api/querystring.md b/doc/api/querystring.md index f1f48fadd5fc29..6d39bebbc83b0a 100644 --- a/doc/api/querystring.md +++ b/doc/api/querystring.md @@ -1,5 +1,7 @@ # Query String + + > Stability: 2 - Stable diff --git a/doc/api/readline.md b/doc/api/readline.md index 2c6e29088544cb..bccee609ed3e8e 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -1,5 +1,7 @@ # Readline + + > Stability: 2 - Stable The `readline` module provides an interface for reading data from a [Readable][] diff --git a/doc/api/repl.md b/doc/api/repl.md index a9d56c5378ab3e..3cac76497a0a47 100644 --- a/doc/api/repl.md +++ b/doc/api/repl.md @@ -1,5 +1,7 @@ # REPL + + > Stability: 2 - Stable The `repl` module provides a Read-Eval-Print-Loop (REPL) implementation that diff --git a/doc/api/stream.md b/doc/api/stream.md index d78bd3e8817ccb..c4378a2f8ac7af 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -1,5 +1,7 @@ # Stream + + > Stability: 2 - Stable A stream is an abstract interface for working with streaming data in Node.js. diff --git a/doc/api/string_decoder.md b/doc/api/string_decoder.md index 17bacf33cbfb9b..2b47317cf0e036 100644 --- a/doc/api/string_decoder.md +++ b/doc/api/string_decoder.md @@ -1,5 +1,7 @@ # String Decoder + + > Stability: 2 - Stable The `string_decoder` module provides an API for decoding `Buffer` objects into diff --git a/doc/api/synopsis.md b/doc/api/synopsis.md index 5e4e22a38b9375..3a9c871d5d5cdc 100644 --- a/doc/api/synopsis.md +++ b/doc/api/synopsis.md @@ -1,5 +1,6 @@ # Usage + `node [options] [v8 options] [script.js | -e "script"] [arguments]` diff --git a/doc/api/timers.md b/doc/api/timers.md index df48905001e19b..010809032c5542 100644 --- a/doc/api/timers.md +++ b/doc/api/timers.md @@ -1,5 +1,7 @@ # Timers + + > Stability: 2 - Stable The `timer` module exposes a global API for scheduling functions to diff --git a/doc/api/tls.md b/doc/api/tls.md index b7e5c8f15e2bf4..12e27959c1c047 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -1,5 +1,7 @@ # TLS (SSL) + + > Stability: 2 - Stable The `tls` module provides an implementation of the Transport Layer Security diff --git a/doc/api/tty.md b/doc/api/tty.md index 963de892cbc0fd..2950eb6db1a396 100644 --- a/doc/api/tty.md +++ b/doc/api/tty.md @@ -1,5 +1,7 @@ # TTY + + > Stability: 2 - Stable The `tty` module provides the `tty.ReadStream` and `tty.WriteStream` classes. diff --git a/doc/api/url.md b/doc/api/url.md index 1cb3e2f89f0fd8..6d0911da81d899 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -1,5 +1,7 @@ # URL + + > Stability: 2 - Stable The `url` module provides utilities for URL resolution and parsing. It can be diff --git a/doc/api/util.md b/doc/api/util.md index 0ab3ba0390bc9d..e44d38706f2c37 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -1,5 +1,7 @@ # Util + + > Stability: 2 - Stable The `util` module is primarily designed to support the needs of Node.js' own diff --git a/doc/api/v8.md b/doc/api/v8.md index 0941596084aea1..234835376bd3e0 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -1,5 +1,7 @@ # V8 + + The `v8` module exposes APIs that are specific to the version of [V8][] built into the Node.js binary. It can be accessed using: diff --git a/doc/api/vm.md b/doc/api/vm.md index 7d04cbd4d1689d..cd47bc04ea85f6 100644 --- a/doc/api/vm.md +++ b/doc/api/vm.md @@ -1,5 +1,7 @@ # VM (Executing JavaScript) + + > Stability: 2 - Stable diff --git a/doc/api/zlib.md b/doc/api/zlib.md index 17a1464b159de3..9edcc7eae37d88 100644 --- a/doc/api/zlib.md +++ b/doc/api/zlib.md @@ -1,5 +1,7 @@ # Zlib + + > Stability: 2 - Stable The `zlib` module provides compression functionality implemented using Gzip and diff --git a/doc/api_assets/style.css b/doc/api_assets/style.css index a9989e9fdcca84..559245c7cef5a4 100644 --- a/doc/api_assets/style.css +++ b/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 { @@ -496,6 +551,9 @@ th > *:last-child, td > *:last-child { #content { font-size: 3.5em; } + #gtoc { + font-size: 0.6em; + } } @media print { diff --git a/doc/template.html b/doc/template.html index 572197beff44fe..d65b56ca5e80ad 100644 --- a/doc/template.html +++ b/doc/template.html @@ -23,11 +23,21 @@

Node.js __VERSION__ Documentation

-

- Index | - View on single page | - View as JSON -

+
diff --git a/tools/doc/html.js b/tools/doc/html.js index bc968f4152155b..49be0ce36fe6fd 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -10,6 +10,7 @@ const typeParser = require('./type-parser.js'); module.exports = toHTML; const STABILITY_TEXT_REG_EXP = /(.*:)\s*(\d)([\s\S]*)/; +const DOC_CREATED_REG_EXP = //; // customized heading without id attribute var renderer = new marked.Renderer(); @@ -31,6 +32,8 @@ var gtocPath = path.resolve(path.join( )); var gtocLoading = null; var gtocData = null; +var docCreated = null; +var nodeVersion = null; /** * opts: input, filename, template, nodeVersion. @@ -39,6 +42,8 @@ function toHTML(opts, cb) { var template = opts.template; var nodeVersion = opts.nodeVersion || process.version; + docCreated = opts.input.match(DOC_CREATED_REG_EXP); + if (gtocData) { return onGtocLoaded(); } @@ -136,6 +141,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); @@ -167,6 +174,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 = `
  • ${v.num}`; + + if (v.lts) + html += ' LTS'; + + return html + '
    • '; + } + + const lis = (vs) => vs.filter(lte).map(li).join('\n'); + + return `
      ${lis(versions)}
    `; +} + // handle general body-text replacements // for example, link man page references to the actual page function parseText(lexed) {