fix broken template processing in jsdoc output (#4381)

because the files generated by jsdoc were output to `docs/_site`, they were not processed as liquid templates, which meant the custom reporter tutorial was broken.

to fix this, we needed to:

1. change the output directory of jsdoc to `docs/api` (just somewhere else)
2. add this to `.gitignore`, obviously
3. tell eleventy to _ignore_ `.gitignore` (just rely on its `.eleventyignore` file)
4. tell eleventy to pass-through all assets underneath `docs/api` (css, images, etc)
5. update the file-loading 11ty data script to output a raw file
6. update the tutorial to use a fenced code block (jsdoc markdown plugin seems to strip html?) and tell Prettier to ignore the liquid template directive

also:

- removed link to google group
- prettier-related reformats
- tweak data script to use `fs.promises`

* update @mocha/docdash

Signed-off-by: Christopher Hiller <[email protected]>

Author: boneskull

.eleventy.js

@@ -16,6 +16,9 @@ module.exports = function(eleventyConfig) {
   eleventyConfig.addPassthroughCopy('docs/_headers');
   eleventyConfig.addPassthroughCopy('docs/favicon.ico');
   eleventyConfig.addPassthroughCopy('docs/example');
+  eleventyConfig.addPassthroughCopy('docs/api/images');
+  eleventyConfig.addPassthroughCopy('docs/api/scripts');
+  eleventyConfig.addPassthroughCopy('docs/api/styles');
 
   /* Markdown Plugins */
   const markdown = require('markdown-it')({
@@ -43,11 +46,12 @@ module.exports = function(eleventyConfig) {
 
   eleventyConfig.setLibrary('md', markdown);
 
+  eleventyConfig.setUseGitIgnore(false);
+
   return {
     passthroughFileCopy: true,
     dir: {
       input: 'docs',
-      includes: '_includes',
       output: 'docs/_site'
     }
   };

.gitignore

@@ -2,6 +2,7 @@
 docs/_site
 docs/_dist
 docs/images/supporters
+docs/api
 mocha.js
 mocha.js.map
 .karma/

docs/.eleventyignore

@@ -5,3 +5,6 @@ LICENSE*
 _dist/
 example/
 changelogs/
+api-tutorials/
+_site/
+

docs/API.md

@@ -1,8 +1,8 @@
 # Mocha's API Documentation
 
-* * *
+---
 
-Congratulations!  You've found Mocha's API documentation.  These docs are for developers who wish to:
+Congratulations! You've found Mocha's API documentation. These docs are for developers who wish to:
 
 - Create an extension for Mocha, or
 - Develop Mocha itself, or
@@ -16,5 +16,4 @@ Otherwise, **you probably want the [main documentation](https://mochajs.org)**.
 - **[Release Notes / History / Changes](https://github.com/mochajs/mocha/blob/master/CHANGELOG.md)**
 - [Code of Conduct](https://github.com/mochajs/mocha/blob/master/.github/CODE_OF_CONDUCT.md)
 - [Gitter Chatroom](https://gitter.im/mochajs/mocha) (ask questions here!)
-- [Google Group](https://groups.google.com/group/mochajs)
 - [Issue Tracker](https://github.com/mochajs/mocha/issues)

docs/_data/files.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const {resolve, relative, dirname} = require('path');
-const {readFileSync} = require('fs');
+const {promises: fs} = require('fs');
 
 const PROJECT_ROOT_DIR = resolve(__dirname, '..', '..');
 const FILES = [
@@ -12,12 +12,9 @@ const FILES = [
   }
 ];
 
-const HEADER = '```js\n';
-const FOOTER = '```\n';
-
-const loadFile = (path, {header} = {}) => {
+const loadFile = async (path, {header} = {}) => {
   const relativeDir = relative(dirname(path), PROJECT_ROOT_DIR);
-  let content = readFileSync(path, 'utf-8');
+  let content = await fs.readFile(path, 'utf-8');
   // replace relative paths in `require()` to root with "mocha".
   // might not work in the general case. not gonna parse an AST for this
   // e.g. `require('../../lib/foo')` => `require('mocha/lib/foo')`
@@ -28,18 +25,19 @@ const loadFile = (path, {header} = {}) => {
       "require('mocha$1')"
     )
     .trim();
-  return `${HEADER}${header}\n\n${content}${FOOTER}`;
+  return `${header}\n\n${content}`;
 };
 
 /**
  * Loads files from disk (see `FILES` above) to be shown as data.
  * Used for embedding sources directly into pages
  */
-module.exports = () => {
-  const files = FILES.map(({path, header, slug}) => {
-    const content = loadFile(path, {header});
-    return {slug, content};
-  });
+module.exports = async () => {
+  const files = [];
+  for await (const {path, header, slug} of FILES) {
+    const content = await loadFile(path, {header});
+    files.push({slug, content});
+  }
   return files.reduce(
     (files, {slug, content}) => ({
       ...files,

docs/api-tutorials/custom-reporter.md

@@ -6,7 +6,10 @@ For example, if `mocha-foo-reporter` was published to the npm registry, you coul
 
 If you're looking to get started quickly, here's an example of a custom reporter:
 
+<!-- prettier-ignore -->
+```js
 {{ files.simplereporter }}
+```
 
 To use this reporter, execute `mocha --reporter /path/to/my-reporter.js`.
 

jsdoc.conf.json

@@ -8,7 +8,7 @@
     "static": false
   },
   "opts": {
-    "destination": "docs/_site/api",
+    "destination": "docs/api",
     "encoding": "utf8",
     "recurse": true,
     "template": "node_modules/@mocha/docdash",