docs: add table-of-contents to troubleshooting (#4234)

Drive-by: teach our table-of-contents generator to ignore comments
inside fenced blocks and to de-linkify titles.

docs/api.md

@@ -3,6 +3,7 @@
 <!-- GEN:empty-if-release --><!-- GEN:stop -->
 - Interactive Documentation: https://pptr.dev
 - API Translations: [中文|Chinese](https://zhaoqize.github.io/puppeteer-api-zh_CN/#/)
+- Troubleshooting: [troubleshooting.md](https://github.com/GoogleChrome/puppeteer/blob/master/docs/troubleshooting.md)
 - Releases per Chromium Version:
   * Chromium 75.0.3738.0 - [Puppeteer v1.14.0](https://github.com/GoogleChrome/puppeteer/blob/v1.14.0/docs/api.md)
   * Chromium 74.0.3723.0 - [Puppeteer v1.13.0](https://github.com/GoogleChrome/puppeteer/blob/v1.13.0/docs/api.md)

docs/troubleshooting.md

@@ -1,5 +1,22 @@
 # Troubleshooting
 
+<!-- GEN:toc -->
+- [Chrome headless doesn't launch](#chrome-headless-doesnt-launch)
+- [Setting Up Chrome Linux Sandbox](#setting-up-chrome-linux-sandbox)
+  * [[recommended] Enable user namespace cloning](#recommended-enable-user-namespace-cloning)
+  * [[alternative] Setup setuid sandbox](#alternative-setup-setuid-sandbox)
+- [Running Puppeteer on Travis CI](#running-puppeteer-on-travis-ci)
+- [Running Puppeteer in Docker](#running-puppeteer-in-docker)
+  * [Running on Alpine](#running-on-alpine)
+    - [Tips](#tips)
+- [Running Puppeteer in the cloud](#running-puppeteer-in-the-cloud)
+  * [Running Puppeteer on Google App Engine](#running-puppeteer-on-google-app-engine)
+  * [Running Puppeteer on Google Cloud Functions](#running-puppeteer-on-google-cloud-functions)
+  * [Running Puppeteer on Heroku](#running-puppeteer-on-heroku)
+  * [Running Puppeteer on AWS Lambda](#running-puppeteer-on-aws-lambda)
+- [Code Transpilation Issues](#code-transpilation-issues)
+<!-- GEN:stop -->
+
 ## Chrome headless doesn't launch
 
 Make sure all the necessary dependencies are installed. You can run `ldd chrome | grep not` on a Linux

utils/doclint/cli.js

@@ -39,7 +39,8 @@ async function run() {
   {
     const readme = await Source.readFile(path.join(PROJECT_DIR, 'README.md'));
     const api = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md'));
-    const mdSources = [readme, api];
+    const troubleshooting = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'troubleshooting.md'));
+    const mdSources = [readme, api, troubleshooting];
 
     const preprocessor = require('./preprocessor');
     messages.push(...await preprocessor.runCommands(mdSources, VERSION));

utils/doclint/preprocessor/index.js

@@ -93,11 +93,22 @@ function applyCommand(command, editText) {
 
 function generateTableOfContents(mdText) {
   const ids = new Set();
-  const titles = mdText.split('\n').map(line => line.trim()).filter(line => line.startsWith('#'));
+  const titles = [];
+  let insideCodeBlock = false;
+  for (const aLine of mdText.split('\n')) {
+    const line = aLine.trim();
+    if (line.startsWith('```')) {
+      insideCodeBlock = !insideCodeBlock;
+      continue;
+    }
+    if (!insideCodeBlock && line.startsWith('#'))
+      titles.push(line);
+  }
   const tocEntries = [];
   for (const title of titles) {
     const [, nesting, name] = title.match(/^(#+)\s+(.*)$/);
-    const id = name.trim().toLowerCase().replace(/\s/g, '-').replace(/[^-0-9a-zа-яё]/ig, '');
+    const delinkifiedName = name.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1');
+    const id = delinkifiedName.trim().toLowerCase().replace(/\s/g, '-').replace(/[^-0-9a-zа-яё]/ig, '');
     let dedupId = id;
     let counter = 0;
     while (ids.has(dedupId))
@@ -105,7 +116,7 @@ function generateTableOfContents(mdText) {
     ids.add(dedupId);
     tocEntries.push({
       level: nesting.length,
-      name,
+      name: delinkifiedName,
       id: dedupId
     });
   }

utils/doclint/preprocessor/test.js

@@ -156,6 +156,42 @@ describe('runCommands', function() {
         #### page.$
         #### page.$$`);
     });
+    it('should work with code blocks', () => {
+      const source = new Source('doc.md', `<!-- gen:toc -->XXX<!-- gen:stop -->
+        ### class: page
+
+        \`\`\`bash
+        # yo comment
+        \`\`\`
+      `);
+      const messages = runCommands([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:toc -->
+- [class: page](#class-page)
+<!-- gen:stop -->
+        ### class: page
+
+        \`\`\`bash
+        # yo comment
+        \`\`\`
+      `);
+    });
+    it('should work with links in titles', () => {
+      const source = new Source('doc.md', `<!-- gen:toc -->XXX<!-- gen:stop -->
+        ### some [link](#foobar) here
+      `);
+      const messages = runCommands([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:toc -->
+- [some link here](#some-link-here)
+<!-- gen:stop -->
+        ### some [link](#foobar) here
+      `);
+    });
   });
   it('should work with multiple commands', function() {
     const source = new Source('doc.md', `