exclude auto-generated contents from docs/index.md; closes #3713

- Remove auto-generated contents from docs/index.md - Make docs/index.md keep excluding auto-generated contents 1. At the pre-processing stage, copy docs/index.md to docs/index.md.tmp 2. Trap exit signals and recover docs/index.md with docs/index.md.tmp after the script execution - Add docs/index.md.tmp to the .gitignore list
mochajs · Feb 16, 2019 · 558cf7d · 558cf7d
1 parent 5d9d3eb
commit 558cf7d
Show file tree

Hide file tree

Showing 3 changed files with 12 additions and 119 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,7 @@
 # Mocha-specific
 docs/_site
 docs/_dist
+docs/index.md.tmp
 mocha.js
 .karma/
 !lib/mocha.js

diff --git a/docs/index.md b/docs/index.md
@@ -51,37 +51,6 @@ Mocha is a feature-rich JavaScript test framework running on [Node.js](https://n
 ## Table of Contents
 
 <!-- AUTO-GENERATED-CONTENT:START (toc:maxdepth=2&bullets=-) -->
-
-- [Installation](#installation)
-- [Getting Started](#getting-started)
-- [Run Cycle Overview](#run-cycle-overview)
-- [Detects Multiple Calls to `done()`](#detects-multiple-calls-to-done)
-- [Assertions](#assertions)
-- [Asynchronous Code](#asynchronous-code)
-- [Synchronous Code](#synchronous-code)
-- [Arrow Functions](#arrow-functions)
-- [Hooks](#hooks)
-- [Pending Tests](#pending-tests)
-- [Exclusive Tests](#exclusive-tests)
-- [Inclusive Tests](#inclusive-tests)
-- [Retry Tests](#retry-tests)
-- [Dynamically Generating Tests](#dynamically-generating-tests)
-- [Timeouts](#timeouts)
-- [Diffs](#diffs)
-- [Command-Line Usage](#command-line-usage)
-- [Interfaces](#interfaces)
-- [Reporters](#reporters)
-- [Running Mocha in the Browser](#running-mocha-in-the-browser)
-- [Desktop Notification Support](#desktop-notification-support)
-- [Configuring Mocha (Node.js)](#configuring-mocha-nodejs)
-- [`mocha.opts`](#mochaopts)
-- [The `test/` Directory](#the-test-directory)
-- [Error Codes](#error-codes)
-- [Editor Plugins](#editor-plugins)
-- [Examples](#examples)
-- [Testing Mocha](#testing-mocha)
-- [More Information](#more-information)
-
 <!-- AUTO-GENERATED-CONTENT:END -->
 
 ## Installation
@@ -814,88 +783,6 @@ Mocha supports the `err.expected` and `err.actual` properties of any thrown `Ass
 ## Command-Line Usage
 
 <!-- AUTO-GENERATED-CONTENT:START (usage:executable=bin/mocha) -->
-
-```plain
-
-mocha [spec..]
-
-Run tests with Mocha
-
-Commands
-  mocha debug [spec..]  Run tests with Mocha                           [default]
-  mocha init <path>     create a client-side Mocha setup at <path>
-
-Rules & Behavior
-  --allow-uncaught           Allow uncaught errors to propagate        [boolean]
-  --async-only, -A           Require all tests to use a callback (async) or
-                             return a Promise                          [boolean]
-  --bail, -b                 Abort ("bail") after first test failure   [boolean]
-  --check-leaks              Check for global variable leaks           [boolean]
-  --delay                    Delay initial execution of root suite     [boolean]
-  --exit                     Force Mocha to quit after tests complete  [boolean]
-  --forbid-only              Fail if exclusive test(s) encountered     [boolean]
-  --forbid-pending           Fail if pending test(s) encountered       [boolean]
-  --global, --globals        List of allowed global variables            [array]
-  --retries                  Retry failed tests this many times         [number]
-  --slow, -s                 Specify "slow" test threshold (in milliseconds)
-                                                          [number] [default: 75]
-  --timeout, -t, --timeouts  Specify test timeout threshold (in milliseconds)
-                                                        [number] [default: 2000]
-  --ui, -u                   Specify user interface    [string] [default: "bdd"]
-
-Reporting & Output
-  --color, -c, --colors                     Force-enable color output  [boolean]
-  --diff                                    Show diff on failure
-                                                       [boolean] [default: true]
-  --full-trace                              Display full stack traces  [boolean]
-  --growl, -G                               Enable Growl notifications [boolean]
-  --inline-diffs                            Display actual/expected differences
-                                            inline within each string  [boolean]
-  --reporter, -R                            Specify reporter to use
-                                                      [string] [default: "spec"]
-  --reporter-option, --reporter-options,    Reporter-specific options
-  -O                                        (<k=v,[k1=v1,..]>)           [array]
-
-Configuration
-  --config   Path to config file                    [default: (nearest rc file)]
-  --opts     Path to `mocha.opts`        [string] [default: "./test/mocha.opts"]
-  --package  Path to package.json for config                            [string]
-
-File Handling
-  --exclude                        Ignore file(s) or glob pattern(s)
-                                                       [array] [default: (none)]
-  --extension, --watch-extensions  File extension(s) to load and/or watch
-                                                           [array] [default: js]
-  --file                           Specify file(s) to be loaded prior to root
-                                   suite execution     [array] [default: (none)]
-  --recursive                      Look for tests in subdirectories    [boolean]
-  --require, -r                    Require module      [array] [default: (none)]
-  --sort, -S                       Sort test files                     [boolean]
-  --watch, -w                      Watch files in the current working directory
-                                   for changes                         [boolean]
-
-Test Filters
-  --fgrep, -f   Only run tests containing this string                   [string]
-  --grep, -g    Only run tests matching this string or regexp           [string]
-  --invert, -i  Inverts --grep and --fgrep matches                     [boolean]
-
-Positional Arguments
-  spec  One or more files, directories, or globs to test
-                                                    [array] [default: ["test/"]]
-
-Other Options
-  --help, -h     Show usage information & exit                         [boolean]
-  --version, -V  Show version number & exit                            [boolean]
-  --interfaces   List built-in user interfaces & exit                  [boolean]
-  --reporters    List built-in reporters & exit                        [boolean]
-
-Mocha Resources
-    Chat: https://gitter.im/mochajs/mocha
-  GitHub: https://github.com/mochajs/mocha.git
-    Docs: https://mochajs.org/
-
-```
-
 <!-- AUTO-GENERATED-CONTENT:END -->
 
 ### `--allow-uncaught`
@@ -1823,8 +1710,5 @@ or the [source](https://github.com/mochajs/mocha/blob/master/lib/mocha.js).
 [mocha-website]: https://mochajs.org/
 [mocha-wiki]: https://github.com/mochajs/mocha/wiki
 
-<!-- AUTO-GENERATED-CONTENT:START (manifest:template=[Gitter]: ${gitter}) -->
-
-[gitter]: https://gitter.im/mochajs/mocha
-
+<!-- AUTO-GENERATED-CONTENT:START (manifest:template=[gitter]: ${gitter}) -->
 <!-- AUTO-GENERATED-CONTENT:END -->
diff --git a/package-scripts.js b/package-scripts.js
@@ -266,11 +266,12 @@ module.exports = {
     docs: {
       default: {
         script:
-          'nps docs.prebuild && eleventy && nps docs.postbuild && nps docs.api',
+          'trap "nps docs.recover" EXIT && nps docs.prebuild && eleventy && nps docs.postbuild && nps docs.api',
         description: 'Build documentation'
       },
       prebuild: {
-        script: 'rimraf docs/_dist docs/_site && nps docs.preprocess',
+        script:
+          'cp docs/index.md docs/index.md.tmp && rimraf docs/_dist docs/_site && nps docs.preprocess',
         description: 'Prepare system for doc building',
         hiddenFromHelp: true
       },
@@ -280,6 +281,13 @@ module.exports = {
         description: 'Post-process docs after build',
         hiddenFromHelp: true
       },
+      recover: {
+        script:
+          'if [ -f docs/index.md.tmp ]; then mv docs/index.md.tmp docs/index.md; fi',
+        description:
+          'Recover docs/index.md to exclude auto-generated documents',
+        hiddenFromHelp: true
+      },
       preprocess: {
         default: {
           script: