doc,tools: allow stability table to be updated

richardlau · danbev · commit cbe3b2716650 · 2021-04-06T06:14:44.000+02:00
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>
diff --git a/doc/api/documentation.md b/doc/api/documentation.md
@@ -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
diff --git a/tools/doc/stability.js b/tools/doc/stability.js
@@ -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'),
@@ -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'));
