add script to automatically dump CLI usage into documentation

[boneskull]

this looks for <!-- usage --> and <!-- usagestop --> in docs/index.md and replaces everything between these two comments with the current output of bin/mocha --help.

[plroebuck]

Why was indentation removed? Running --help on most programs displays cmdline options with indentation.

[boneskull]

probably has to do with the lack of a tty somewhere.

the actual bin/mocha --help output has indents.

[plroebuck]

That's what I thought this was supposed to do -- run mocha --help and paste its exact content.

[boneskull]

it does, but the exact content when run without a terminal window doesn't have the leading indents, ostensibly because process.stdout.columns is undefined.

I don't know how to force this value to be present unless I monkeypatch it; it comes out of Node.js internals. it'd need to be monkeypatched for this script only, which is honestly more effort than I'd like to go to... if you can figure out how to fake a tty for this, go ahead and make the necessary changes. I'm curious about the solution, anyway!

[coveralls]

Coverage remained the same at 90.495% when pulling bded805 on auto-doc-usage into 9f02180 on master.

[plroebuck]

So if a usage codefence is already present? When would that not be the case?

[boneskull]

no, meaning, if we have

<!-- usage -->
STUFF
<!-- usagestop -->

we hit the first branch, otherwise if we have this (whitespace or nothing):

<!-- usage -->

<!-- usagestop -->

we hit the second.

[plroebuck]

no, meaning, if we have

<!-- usage -->
STUFF
<!-- usagestop -->

we hit the first branch, otherwise if we have this (whitespace or nothing):

<!-- usage -->

<!-- usagestop -->

we hit the second.

Well, that was what I assumed, where STUFF=code fence. Just not following when the second case would ever occur.

[boneskull]

merging this; if there are further concerns, please send edits

[plroebuck]

Well, guess it doesn't matter since it's already merged...

[plroebuck]

Move "mississippi" to L513.5

[plroebuck]

Why not done alphabetically?

[plroebuck]

no, meaning, if we have

<!-- usage -->
STUFF
<!-- usagestop -->

we hit the first branch, otherwise if we have this (whitespace or nothing):

<!-- usage -->

<!-- usagestop -->

we hit the second.

Well, that was what I assumed, where STUFF=code fence. Just not following when the second case would ever occur.

[plroebuck]

Don't you need a catch here?

updateTOC().then(updateUsage()).catch((err) => {
  const script = path.basename(
    require.main.filename, path.extname(require.main.filename)
  );
  console.error(`${script}:`, err);
});