fix: process documentation during publishing (#8433)

2024-06-14 14:02:48 +00:00 · 2022-05-30 21:50:34 +02:00
parent 54efc2c949
commit d111d19f78
18 changed files with 107 additions and 168 deletions
--- a/utils/doclint/cli.js
+++ b/utils/doclint/cli.js
@@ -29,6 +29,7 @@ const YELLOW_COLOR = '\x1b[33m';
 const RESET_COLOR = '\x1b[0m';

 const IS_RELEASE = Boolean(process.env.IS_RELEASE);
+const IS_PRE_RELEASE = Boolean(process.env.IS_PRE_RELEASE);

 run();

@@ -39,7 +40,7 @@ async function run() {
  const messages = [];
  let changedFiles = false;

-  if (IS_RELEASE) {
+  if (IS_RELEASE || IS_PRE_RELEASE) {
    const versions = await Source.readFile(
      path.join(PROJECT_DIR, 'versions.js')
    );
@@ -61,9 +62,15 @@ async function run() {
  const mdSources = [readme, api, troubleshooting, contributing];

  const preprocessor = require('./preprocessor/index.js');
-  messages.push(...(await preprocessor.runCommands(mdSources, VERSION)));
  messages.push(
-    ...(await preprocessor.ensureReleasedAPILinks([readme], VERSION))
+    ...(await preprocessor.runCommands(mdSources, VERSION, IS_RELEASE))
+  );
+  messages.push(
+    ...(await preprocessor.ensureReleasedAPILinks(
+      [readme],
+      VERSION,
+      IS_RELEASE
+    ))
  );

  const browser = await puppeteer.launch();
--- a/utils/doclint/preprocessor/index.js
+++ b/utils/doclint/preprocessor/index.js
@@ -16,14 +16,16 @@

 const Message = require('../Message.js');

-const IS_RELEASE = Boolean(process.env.IS_RELEASE);
-
-module.exports.ensureReleasedAPILinks = function (sources, version) {
+module.exports.ensureReleasedAPILinks = function (
+  sources,
+  version,
+  isReleaseVersion
+) {
  // Release version is everything that doesn't include "-".
  const apiLinkRegex =
-    /https:\/\/github.com\/puppeteer\/puppeteer\/blob\/v[^/]*\/docs\/api.md/gi;
-  const lastReleasedAPI = `https://github.com/puppeteer/puppeteer/blob/v${
-    version.split('-')[0]
+    /https:\/\/github.com\/puppeteer\/puppeteer\/blob\/[^/]*\/docs\/api.md/gi;
+  const lastReleasedAPI = `https://github.com/puppeteer/puppeteer/blob/${
+    isReleaseVersion ? `v${version}` : 'main'
  }/docs/api.md`;

  const messages = [];
@@ -36,10 +38,7 @@ module.exports.ensureReleasedAPILinks = function (sources, version) {
  return messages;
 };

-module.exports.runCommands = function (sources, version) {
-  // Release version is everything that doesn't include "-".
-  const isReleaseVersion = IS_RELEASE || !version.includes('-');
-
+module.exports.runCommands = function (sources, version, isReleaseVersion) {
  const messages = [];
  const commands = [];
  for (const source of sources) {
@@ -72,22 +71,31 @@ module.exports.runCommands = function (sources, version) {
  commands.sort((a, b) => b.from - a.from);
  for (const command of commands) {
    let newText = null;
-    if (command.name === 'version')
-      newText = isReleaseVersion ? `v${version}` : 'Tip-Of-Tree';
-    else if (command.name === 'empty-if-release')
-      newText = isReleaseVersion ? '' : command.originalText;
-    else if (command.name === 'toc')
-      newText = generateTableOfContents(
-        command.source.text().substring(command.to)
-      );
-    else if (command.name === 'versions-per-release')
-      newText = generateVersionsPerRelease();
-    if (newText === null)
+    switch (command.name) {
+      case 'version':
+        newText = isReleaseVersion ? `v${version}` : 'Tip-Of-Tree';
+        break;
+      case 'empty-if-release':
+        newText = isReleaseVersion ? '' : command.originalText;
+        break;
+      case 'toc':
+        newText = generateTableOfContents(
+          command.source.text().substring(command.to)
+        );
+        break;
+      case 'versions-per-release':
+        newText = generateVersionsPerRelease();
+        break;
+    }
+    if (newText === null) {
      messages.push(Message.error(`Unknown command 'gen:${command.name}'`));
-    else if (applyCommand(command, newText)) changedSources.add(command.source);
+    } else if (applyCommand(command, newText)) {
+      changedSources.add(command.source);
+    }
  }
-  for (const source of changedSources)
+  for (const source of changedSources) {
    messages.push(Message.info(`GEN: updated ${source.projectPath()}`));
+  }
  return messages;
 };

--- a/utils/doclint/preprocessor/preprocessor.spec.js
+++ b/utils/doclint/preprocessor/preprocessor.spec.js
@@ -20,21 +20,6 @@ const expect = require('expect');

 describe('doclint preprocessor specs', function () {
  describe('ensureReleasedAPILinks', function () {
-    it('should work with non-release version', function () {
-      const source = new Source(
-        'doc.md',
-        `
-      [API](https://github.com/puppeteer/puppeteer/blob/v1.1.0/docs/api.md#class-page)
-    `
-      );
-      const messages = ensureReleasedAPILinks([source], '1.3.0-post');
-      expect(messages.length).toBe(1);
-      expect(messages[0].type).toBe('warning');
-      expect(messages[0].text).toContain('doc.md');
-      expect(source.text()).toBe(`
-      [API](https://github.com/puppeteer/puppeteer/blob/v1.3.0/docs/api.md#class-page)
-    `);
-    });
    it('should work with release version', function () {
      const source = new Source(
        'doc.md',
@@ -42,22 +27,22 @@ describe('doclint preprocessor specs', function () {
      [API](https://github.com/puppeteer/puppeteer/blob/v1.1.0/docs/api.md#class-page)
    `
      );
-      const messages = ensureReleasedAPILinks([source], '1.3.0');
+      const messages = ensureReleasedAPILinks([source], '1.3.0', true);
      expect(messages.length).toBe(1);
-      expect(messages[0].type).toBe('warning');
+      expect(messages[0].type).toBe('info');
      expect(messages[0].text).toContain('doc.md');
      expect(source.text()).toBe(`
      [API](https://github.com/puppeteer/puppeteer/blob/v1.3.0/docs/api.md#class-page)
    `);
    });
-    it('should keep main branch links intact', function () {
+    it('should keep main branch links intact on non-release', function () {
      const source = new Source(
        'doc.md',
        `
      [API](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#class-page)
    `
      );
-      const messages = ensureReleasedAPILinks([source], '1.3.0');
+      const messages = ensureReleasedAPILinks([source], '1.3.0', false);
      expect(messages.length).toBe(0);
      expect(source.text()).toBe(`
      [API](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#class-page)
@@ -73,7 +58,7 @@ describe('doclint preprocessor specs', function () {
      <!-- gen:unknown-command -->something<!-- gen:stop -->
    `
      );
-      const messages = runCommands([source], '1.1.1');
+      const messages = runCommands([source], '1.1.1', true);
      expect(source.hasUpdatedText()).toBe(false);
      expect(messages.length).toBe(1);
      expect(messages[0].type).toBe('error');
@@ -87,9 +72,9 @@ describe('doclint preprocessor specs', function () {
        Puppeteer <!-- gen:version -->XXX<!-- gen:stop -->
      `
        );
-        const messages = runCommands([source], '1.2.0');
+        const messages = runCommands([source], '1.2.0', true);
        expect(messages.length).toBe(1);
-        expect(messages[0].type).toBe('warning');
+        expect(messages[0].type).toBe('info');
        expect(messages[0].text).toContain('doc.md');
        expect(source.text()).toBe(`
        Puppeteer <!-- gen:version -->v1.2.0<!-- gen:stop -->
@@ -102,9 +87,9 @@ describe('doclint preprocessor specs', function () {
        Puppeteer <!-- gen:version -->XXX<!-- gen:stop -->
      `
        );
-        const messages = runCommands([source], '1.2.0-post');
+        const messages = runCommands([source], '1.2.0', false);
        expect(messages.length).toBe(1);
-        expect(messages[0].type).toBe('warning');
+        expect(messages[0].type).toBe('info');
        expect(messages[0].text).toContain('doc.md');
        expect(source.text()).toBe(`
        Puppeteer <!-- gen:version -->Tip-Of-Tree<!-- gen:stop -->
@@ -116,14 +101,14 @@ describe('doclint preprocessor specs', function () {
          `Puppeteer v<!--   gEn:version -->WHAT
 <!--     GEN:stop   -->`
        );
-        runCommands([source], '1.1.1');
+        runCommands([source], '1.1.1', true);
        expect(source.text()).toBe(
          `Puppeteer v<!--   gEn:version -->v1.1.1<!--     GEN:stop   -->`
        );
      });
      it('should not tolerate missing gen:stop', function () {
        const source = new Source('doc.md', `<!--GEN:version-->`);
-        const messages = runCommands([source], '1.2.0');
+        const messages = runCommands([source], '1.2.0', true);
        expect(source.hasUpdatedText()).toBe(false);
        expect(messages.length).toBe(1);
        expect(messages[0].type).toBe('error');
@@ -138,9 +123,9 @@ describe('doclint preprocessor specs', function () {
        <!-- gen:empty-if-release -->XXX<!-- gen:stop -->
      `
        );
-        const messages = runCommands([source], '1.1.1');
+        const messages = runCommands([source], '1.1.1', true);
        expect(messages.length).toBe(1);
-        expect(messages[0].type).toBe('warning');
+        expect(messages[0].type).toBe('info');
        expect(messages[0].text).toContain('doc.md');
        expect(source.text()).toBe(`
        <!-- gen:empty-if-release --><!-- gen:stop -->
@@ -153,7 +138,7 @@ describe('doclint preprocessor specs', function () {
        <!-- gen:empty-if-release -->XXX<!-- gen:stop -->
      `
        );
-        const messages = runCommands([source], '1.1.1-post');
+        const messages = runCommands([source], '1.1.1', false);
        expect(messages.length).toBe(0);
        expect(source.text()).toBe(`
        <!-- gen:empty-if-release -->XXX<!-- gen:stop -->
@@ -169,9 +154,9 @@ describe('doclint preprocessor specs', function () {
        #### page.$
        #### page.$$`
        );
-        const messages = runCommands([source], '1.3.0');
+        const messages = runCommands([source], '1.3.0', true);
        expect(messages.length).toBe(1);
-        expect(messages[0].type).toBe('warning');
+        expect(messages[0].type).toBe('info');
        expect(messages[0].text).toContain('doc.md');
        expect(source.text()).toBe(`<!-- gen:toc -->
 - [class: page](#class-page)
@@ -193,9 +178,9 @@ describe('doclint preprocessor specs', function () {
        \`\`\`
      `
        );
-        const messages = runCommands([source], '1.3.0');
+        const messages = runCommands([source], '1.3.0', true);
        expect(messages.length).toBe(1);
-        expect(messages[0].type).toBe('warning');
+        expect(messages[0].type).toBe('info');
        expect(messages[0].text).toContain('doc.md');
        expect(source.text()).toBe(`<!-- gen:toc -->
 - [class: page](#class-page)
@@ -214,9 +199,9 @@ describe('doclint preprocessor specs', function () {
        ### some [link](#foobar) here
      `
        );
-        const messages = runCommands([source], '1.3.0');
+        const messages = runCommands([source], '1.3.0', true);
        expect(messages.length).toBe(1);
-        expect(messages[0].type).toBe('warning');
+        expect(messages[0].type).toBe('info');
        expect(messages[0].text).toContain('doc.md');
        expect(source.text()).toBe(`<!-- gen:toc -->
 - [some link here](#some-link-here)
@@ -234,9 +219,9 @@ describe('doclint preprocessor specs', function () {
      <!-- gen:version -->ZZZ<!-- gen:stop -->
    `
      );
-      const messages = runCommands([source], '1.1.1');
+      const messages = runCommands([source], '1.1.1', true);
      expect(messages.length).toBe(1);
-      expect(messages[0].type).toBe('warning');
+      expect(messages[0].type).toBe('info');
      expect(messages[0].text).toContain('doc.md');
      expect(source.text()).toBe(`
      <!-- gen:version -->v1.1.1<!-- gen:stop -->