diff options
| -rw-r--r-- | Makefile | 6 | ||||
| -rw-r--r-- | doc/api/documentation.md | 3 | ||||
| -rw-r--r-- | doc/api_assets/style.css | 4 | ||||
| -rw-r--r-- | tools/doc/alljson.js | 3 | ||||
| -rw-r--r-- | tools/doc/stability.js | 111 |
5 files changed, 126 insertions, 1 deletions
@@ -696,7 +696,7 @@ doc-only: tools/doc/node_modules \ @if [ "$(shell $(node_use_openssl))" != "true" ]; then \ echo "Skipping doc-only (no crypto)"; \ else \ - $(MAKE) out/doc/api/all.html out/doc/api/all.json; \ + $(MAKE) out/doc/api/all.html out/doc/api/all.json out/doc/api/stability; \ fi .PHONY: doc @@ -749,6 +749,10 @@ out/doc/api/all.html: $(apidocs_html) tools/doc/allhtml.js \ out/doc/api/all.json: $(apidocs_json) tools/doc/alljson.js | out/doc/api $(call available-node, tools/doc/alljson.js) +.PHONY: out/doc/api/stability +out/doc/api/stability: out/doc/api/all.json tools/doc/stability.js | out/doc/api + $(call available-node, tools/doc/stability.js) + .PHONY: docopen docopen: out/doc/api/all.html @$(PYTHON) -mwebbrowser file://$(abspath $<) diff --git a/doc/api/documentation.md b/doc/api/documentation.md index 979d85ef0a3..d39aa30438a 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -43,6 +43,9 @@ Bugs or behavior changes may surprise users when Experimental API modifications occur. To avoid surprises, use of an Experimental feature may need a command-line flag. Experimental features may also emit a [warning][]. +## Stability overview +<!-- STABILITY_OVERVIEW_SLOT --> + ## JSON output <!-- YAML added: v0.6.12 diff --git a/doc/api_assets/style.css b/doc/api_assets/style.css index e7ecfd264ad..a6c8f47872a 100644 --- a/doc/api_assets/style.css +++ b/doc/api_assets/style.css @@ -263,6 +263,10 @@ ol.version-picker li:last-child a { background-color: var(--green2); } +.module_stability { + vertical-align: middle; +} + .api_metadata { font-size: .85rem; margin-bottom: 1rem; diff --git a/tools/doc/alljson.js b/tools/doc/alljson.js index 7e027f764e7..0d697dde01d 100644 --- a/tools/doc/alljson.js +++ b/tools/doc/alljson.js @@ -43,6 +43,9 @@ for (const link of toc.match(/<a.*?>/g)) { for (const property in data) { if (results.hasOwnProperty(property)) { + data[property].forEach((mod) => { + mod.source = data.source; + }); results[property].push(...data[property]); } } diff --git a/tools/doc/stability.js b/tools/doc/stability.js new file mode 100644 index 00000000000..ca4158ebc9a --- /dev/null +++ b/tools/doc/stability.js @@ -0,0 +1,111 @@ +'use strict'; + +// Build stability table to documentation.html/json/md by generated all.json + +const fs = require('fs'); +const path = require('path'); +const unified = require('unified'); +const raw = require('rehype-raw'); +const markdown = require('remark-parse'); +const htmlStringify = require('rehype-stringify'); +const gfm = require('remark-gfm'); +const remark2rehype = require('remark-rehype'); +const visit = require('unist-util-visit'); + +const source = `${__dirname}/../../out/doc/api`; +const data = require(path.join(source, 'all.json')); +const mark = '<!-- STABILITY_OVERVIEW_SLOT -->'; + +const output = { + json: path.join(source, 'stability.json'), + docHTML: path.join(source, 'documentation.html'), + docJSON: path.join(source, 'documentation.json'), + docMarkdown: path.join(source, 'documentation.md'), +}; + +function collectStability(data) { + const stability = []; + + for (const mod of data.modules) { + if (mod.displayName && mod.stability >= 0) { + const link = mod.source.replace('doc/api/', '').replace('.md', '.html'); + // const link = re.exec(toc)[1] + stability.push({ + api: mod.name, + link: link, + stability: mod.stability, + stabilityText: `(${mod.stability}) ${mod.stabilityText}`, + }); + } + } + + stability.sort((a, b) => a.api.localeCompare(b.api)); + return stability; +} + +function createMarkdownTable(data) { + const md = ['| API | Stability |', '| --- | --------- |']; + + for (const mod of data) { + md.push(`| [${mod.api}](${mod.link}) | ${mod.stabilityText} |`); + } + + return md.join('\n'); +} + +function createHTML(md) { + const file = unified() + .use(markdown) + .use(gfm) + .use(remark2rehype, { allowDangerousHtml: true }) + .use(raw) + .use(htmlStringify) + .use(processStability) + .processSync(md); + + return file.contents.trim(); +} + +function processStability() { + return (tree) => { + visit(tree, { type: 'element', tagName: 'tr' }, (node) => { + const [api, stability] = node.children; + if (api.tagName !== 'td') { + return; + } + + api.properties.class = 'module_stability'; + + const level = stability.children[0].value[1]; + stability.properties.class = `api_stability api_stability_${level}`; + }); + }; +} + +function updateStabilityMark(file, value, mark) { + const fd = fs.openSync(file, 'r+'); + const content = fs.readFileSync(fd); + + // Find the position of the `mark`. + const index = content.indexOf(mark); + + // Overwrite the mark with `value` parameter. + const offset = fs.writeSync(fd, value, index, 'utf-8'); + + // Re-write the end of the file after `value`. + fs.writeSync(fd, content, index + mark.length, undefined, index + offset); + fs.closeSync(fd); +} + +const stability = collectStability(data); + +// add markdown +const markdownTable = createMarkdownTable(stability); +updateStabilityMark(output.docMarkdown, markdownTable, mark); + +// add html table +const html = createHTML(markdownTable); +updateStabilityMark(output.docHTML, html, mark); + +// add json output +updateStabilityMark(output.docJSON, JSON.stringify(html), JSON.stringify(mark)); |