From 531344446479e17f161b27d83b2a7db9fc189310 Mon Sep 17 00:00:00 2001 From: Zijian Liu Date: Sun, 22 Nov 2020 17:39:25 +0800 Subject: [PATCH 1/6] doc: list the stability status of each API Fixes: https://github.com/nodejs/node/issues/23723 --- Makefile | 5 +- doc/api/documentation.md | 3 ++ doc/api_assets/style.css | 4 ++ tools/doc/alljson.js | 3 ++ tools/doc/stability.js | 102 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 116 insertions(+), 1 deletion(-) create mode 100644 tools/doc/stability.js diff --git a/Makefile b/Makefile index 4a6e59536bb4d2..6c16dbda40da7a 100644 --- a/Makefile +++ b/Makefile @@ -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,9 @@ 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) +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 979d85ef0a3005..d39aa30438aefc 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 + + ## JSON output '; + +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 content = fs.readFileSync(file, { encoding: 'utf-8' }); + const newContent = content.replace(mark, value); + fs.writeFileSync(file, newContent, { encoding: 'utf-8' }); +} + +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), `"${mark}"`); From 70979d29296f064318e92baf47d8459b8b0fe38c Mon Sep 17 00:00:00 2001 From: Lxxyx Date: Tue, 19 Jan 2021 12:26:17 +0800 Subject: [PATCH 2/6] Update Makefile Co-authored-by: Antoine du Hamel --- Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/Makefile b/Makefile index 6c16dbda40da7a..c0aaa1156be3e2 100644 --- a/Makefile +++ b/Makefile @@ -749,6 +749,7 @@ 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) From 32d333ca9f2dcaa3ee1efd30b116f0817f7c119f Mon Sep 17 00:00:00 2001 From: Lxxyx Date: Tue, 19 Jan 2021 17:38:43 +0800 Subject: [PATCH 3/6] Update tools/doc/stability.js Co-authored-by: Antoine du Hamel --- tools/doc/stability.js | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/tools/doc/stability.js b/tools/doc/stability.js index 637fb6aa3666c4..79a378436fe3f6 100644 --- a/tools/doc/stability.js +++ b/tools/doc/stability.js @@ -83,9 +83,18 @@ function processStability() { } function updateStabilityMark(file, value, mark) { - const content = fs.readFileSync(file, { encoding: 'utf-8' }); - const newContent = content.replace(mark, value); - fs.writeFileSync(file, newContent, { encoding: 'utf-8' }); + 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. + fs.writeSync(fd, value, index, 'utf-8'); + + // Re-write the end of the file after `value`. + fs.writeSync(fd, content, index + mark.length); + fs.closeSync(fd); } const stability = collectStability(data); From 579c21cf3d0d113b2ca1963d2c69a8244373453f Mon Sep 17 00:00:00 2001 From: Lxxyx Date: Tue, 19 Jan 2021 19:13:28 +0800 Subject: [PATCH 4/6] Update tools/doc/stability.js Co-authored-by: Antoine du Hamel --- tools/doc/stability.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/doc/stability.js b/tools/doc/stability.js index 79a378436fe3f6..c07706a520ed99 100644 --- a/tools/doc/stability.js +++ b/tools/doc/stability.js @@ -90,7 +90,7 @@ function updateStabilityMark(file, value, mark) { const index = content.indexOf(mark); // Overwrite the mark with `value` parameter. - fs.writeSync(fd, value, index, 'utf-8'); + 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); From 8c573d10c63d7d5ea511a212444cd62eced3faa1 Mon Sep 17 00:00:00 2001 From: Lxxyx Date: Tue, 19 Jan 2021 19:13:40 +0800 Subject: [PATCH 5/6] Update tools/doc/stability.js Co-authored-by: Antoine du Hamel --- tools/doc/stability.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/doc/stability.js b/tools/doc/stability.js index c07706a520ed99..d828764fd6e618 100644 --- a/tools/doc/stability.js +++ b/tools/doc/stability.js @@ -93,7 +93,7 @@ function updateStabilityMark(file, value, mark) { 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); + fs.writeSync(fd, content, index + mark.length, undefined, index + offset); fs.closeSync(fd); } From f0103c6b9b70ca2d00821b248a257deb2babb7bc Mon Sep 17 00:00:00 2001 From: Lxxyx Date: Tue, 19 Jan 2021 19:19:08 +0800 Subject: [PATCH 6/6] Update tools/doc/stability.js Co-authored-by: Antoine du Hamel --- tools/doc/stability.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/doc/stability.js b/tools/doc/stability.js index d828764fd6e618..ca4158ebc9a77e 100644 --- a/tools/doc/stability.js +++ b/tools/doc/stability.js @@ -108,4 +108,4 @@ const html = createHTML(markdownTable); updateStabilityMark(output.docHTML, html, mark); // add json output -updateStabilityMark(output.docJSON, JSON.stringify(html), `"${mark}"`); +updateStabilityMark(output.docJSON, JSON.stringify(html), JSON.stringify(mark));