Skip to content

Commit

Permalink
doc,tools: allow stability table to be updated
Browse files Browse the repository at this point in the history
Keep markers for the stability table so that it can be updated on
subsequent runs of the doc tooling. Only overwrite the files if
they have been changed.

PR-URL: #38048
Fixes: #37886
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Juan José Arboleda <soyjuanarbol@gmail.com>
  • Loading branch information
richardlau authored and danbev committed Apr 6, 2021
1 parent a9332e8 commit cbe3b27
Show file tree
Hide file tree
Showing 2 changed files with 18 additions and 14 deletions.
3 changes: 2 additions & 1 deletion doc/api/documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,8 @@ 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 -->
<!-- STABILITY_OVERVIEW_SLOT_BEGIN -->
<!-- STABILITY_OVERVIEW_SLOT_END -->

## JSON output
<!-- YAML
Expand Down
29 changes: 16 additions & 13 deletions tools/doc/stability.js
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,9 @@ 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 markBegin = '<!-- STABILITY_OVERVIEW_SLOT_BEGIN -->';
const markEnd = '<!-- STABILITY_OVERVIEW_SLOT_END -->';
const mark = `${markBegin}(.*)${markEnd}`;

const output = {
json: path.join(source, 'stability.json'),
Expand Down Expand Up @@ -84,28 +86,29 @@ function processStability() {

function updateStabilityMark(file, value, mark) {
const fd = fs.openSync(file, 'r+');
const content = fs.readFileSync(fd);
const content = fs.readFileSync(fd, { encoding: 'utf8' });

// 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);
const replaced = content.replace(mark, value);
if (replaced !== content) {
fs.writeSync(fd, replaced, 0, 'utf8');
}
fs.closeSync(fd);
}

const stability = collectStability(data);

// add markdown
const markdownTable = createMarkdownTable(stability);
updateStabilityMark(output.docMarkdown, markdownTable, mark);
updateStabilityMark(output.docMarkdown,
`${markBegin}\n${markdownTable}\n${markEnd}`,
new RegExp(mark, 's'));

// add html table
const html = createHTML(markdownTable);
updateStabilityMark(output.docHTML, html, mark);
updateStabilityMark(output.docHTML, `${markBegin}${html}${markEnd}`,
new RegExp(mark, 's'));

// add json output
updateStabilityMark(output.docJSON, JSON.stringify(html), JSON.stringify(mark));
updateStabilityMark(output.docJSON,
JSON.stringify(`${markBegin}${html}${markEnd}`),
new RegExp(JSON.stringify(mark), 's'));

0 comments on commit cbe3b27

Please sign in to comment.