chore: link to the latest-released API from the README.md (#2449)

This patch adds a preprocessor command to link to the latest-released
API from the README.md.

Fixes #1923.

README.md

@@ -6,7 +6,7 @@
 
 <img src="https://user-images.githubusercontent.com/10379601/29446482-04f7036a-841f-11e7-9872-91d1fc2ea683.png" height="200" align="right">
 
-###### [API](docs/api.md) | [FAQ](#faq) | [Contributing](https://github.com/GoogleChrome/puppeteer/blob/master/CONTRIBUTING.md)
+###### <!-- gen:last-released-api -->[API](https://github.com/GoogleChrome/puppeteer/blob/v1.3.0/docs/api.md)<!-- gen:stop --> | [FAQ](#faq) | [Contributing](https://github.com/GoogleChrome/puppeteer/blob/master/CONTRIBUTING.md)
 
 > Puppeteer is a Node library which provides a high-level API to control [headless](https://developers.google.com/web/updates/2017/04/headless-chrome) Chrome or Chromium over the [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/). It can also be configured to use full (non-headless) Chrome or Chromium.
 

utils/doclint/cli.js

@@ -37,8 +37,10 @@ async function run() {
 
   // Documentation checks.
   {
-    const apiSource = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md'));
+    const mdSources = await Promise.all([
-    const mdSources = [apiSource];
+      Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md')),
+      Source.readFile(path.join(PROJECT_DIR, 'README.md'))
+    ]);
 
     const toc = require('./toc');
     messages.push(...await toc(mdSources));

utils/doclint/preprocessor/index.js

@@ -19,6 +19,8 @@ const Message = require('../Message');
 module.exports = function(sources, version) {
   // Release version is everything that doesn't include "-".
   const isReleaseVersion = !version.includes('-');
+  const lastReleasedAPILink = `[API](https://github.com/GoogleChrome/puppeteer/blob/v${version.split('-')[0]}/docs/api.md)`;
+
   const messages = [];
   const commands = [];
   for (const source of sources) {
@@ -52,6 +54,8 @@ module.exports = function(sources, version) {
       newText = isReleaseVersion ? 'v' + version : 'Tip-Of-Tree';
     else if (command.name === 'empty-if-release')
       newText = isReleaseVersion ? '' : command.originalText;
+    else if (command.name === 'last-released-api')
+      newText = lastReleasedAPILink;
     if (newText === null)
       messages.push(Message.error(`Unknown command 'gen:${command.name}'`));
     else if (applyCommand(command, newText))

utils/doclint/preprocessor/test.js

@@ -100,6 +100,32 @@ describe('preprocessor', function() {
       `);
     });
   });
+  describe('gen:empty-if-release', function() {
+    it('should work with non-release version', function() {
+      const source = new Source('doc.md', `
+        <!-- gen:last-released-api -->XXX<!-- gen:stop -->
+      `);
+      const messages = preprocessor([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(`
+        <!-- gen:last-released-api -->[API](https://github.com/GoogleChrome/puppeteer/blob/v1.3.0/docs/api.md)<!-- gen:stop -->
+      `);
+    });
+    it('should work with release version', function() {
+      const source = new Source('doc.md', `
+        <!-- gen:last-released-api -->XXX<!-- gen:stop -->
+      `);
+      const messages = preprocessor([source], '1.3.0');
+      expect(messages.length).toBe(1);
+      expect(messages[0].type).toBe('warning');
+      expect(messages[0].text).toContain('doc.md');
+      expect(source.text()).toBe(`
+        <!-- gen:last-released-api -->[API](https://github.com/GoogleChrome/puppeteer/blob/v1.3.0/docs/api.md)<!-- gen:stop -->
+      `);
+    });
+  });
   it('should work with multiple commands', function() {
     const source = new Source('doc.md', `
       <!-- gen:version -->XXX<!-- gen:stop -->