From 20883114625f67cbf6f1dff561651cb33de0de4f Mon Sep 17 00:00:00 2001
From: Richard Lau <rlau@redhat.com>
Date: Fri, 2 Apr 2021 15:27:19 -0400
Subject: [PATCH] doc,tools: allow stability table to be updated

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.
---
 doc/api/documentation.md |  3 ++-
 tools/doc/stability.js   | 29 ++++++++++++++++-------------
 2 files changed, 18 insertions(+), 14 deletions(-)

diff --git a/doc/api/documentation.md b/doc/api/documentation.md
index d0a05262cc1f27..6277e3a869bfaf 100644
--- 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
index 2eb5816e4da0a8..9ab6fac827e59e 100644
--- 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,16 +86,12 @@ 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);
 }
 
@@ -101,11 +99,16 @@ 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'));