CLI docs using only markdown

[JackuB]

Transforming CLI help to a plain markdown to improve the editing experience and portability.

[github-actions]

	Warnings
⚠️	Since the CLI is unifying on a standard and improved tooling, we're starting to migrate old-style imports and exports to ES6 ones. A file you've modified is using either module.exports or require(). If you can, please update them to ES6 import syntax and export syntax. Files found: webpack.common.ts webpack.prod.ts

	Messages
📖	You are modifying something in test/smoke directory, yet you are not on the branch starting with smoke/. You can prefix your branch with smoke/ and Smoke tests will trigger for this PR.

Generated by 🚫 dangerJS against 9aa0478

[aron]

Added some suggestions inline to fix broken links and some minor formatting inconsistencies and broken likes but otherwise looks good to me 👍

[ghost]

Looks good. This will reduce a lot of PR friction around updating docs. 🎉

I've left a bunch of improvements we can make, but I don't think we should block this PR as it's greatly improving what we currently have. I'm mostly leaving comments to go back to later as this PR is huge.

Let's discuss later.

[ghost]

The cause of this issue mentioned yesterday is likely because webpack.common's default export does not have an assigned type. So every usage needs the as Configuration to bypass TypeScript.

This can be avoided by assigning the type in webpack.common.

[Avishagp]

Thank you so much for explaining!

[ghost]

It would be nice to have tests for this as it's pretty complex and hard to know what each step is for.

[ghost]

(Repeating myself) It would be nice to have tests for this as it's pretty complex and hard to know what each step is for.

[ghost]

externals is a bit of a mess, so forcing TypeScript to assume it's string[] might cause weird bugs in the future. We could move the object to its own module and type and import it here and in webpack.common. That'd make it typesafe.

Here's the type for reference:

type Externals =
	| string
	| RegExp
	| ExternalItem[]
	| (ExternalItemObjectKnown & ExternalItemObjectUnknown)
	| ((
			data: ExternalItemFunctionData,
			callback: (
				err?: Error,
				result?: string | boolean | string[] | { [index: string]: any }
			) => void
	  ) => void)
	| ((data: ExternalItemFunctionData) => Promise<ExternalItemValue>);

[ghost]

Other notes: we should write tests for this script. Maybe consider removing externals logic entirely as it's empty. We can bring it back if/when we need it.

[ghost]

We should move this execution to its own module like generate-help.ts. Having modules with both side-effects and exports will cause issues for dependant modules importing from it.

[ghost]

I think we can integrate our help docs more closely with Webpack and let it do the hard work around watching, generating and bundling docs. Can't summarise the process in a comment box so let's discuss later.

[ghost]

Why don't we want Prettier to format -docs? 🤔

[ghost]

I don't think we need this "directories" key at all. It's just CommonJS metadata that nothing seems to be using.

https://docs.npmjs.com/cli/v8/configuring-npm/package-json#directories

http://wiki.commonjs.org/wiki/Packages/1.0

Less maintenance for us if we remove it.