Generated docs for the command line are worse than the actual command line

[markstos]

This issue is about the docs here:

https://molecule.readthedocs.io/en/latest/usage.html

These docs clarify that Check means "Check Command Class" and "targets the default scenario". While Converge is defined in terms of itself "Converge will execute the sequence necessary to converge the instances." and molecule converge "targets the default scenario".

Since What "check" and "converge" do are not clearly defined, the rest of the docs in these sections are not meaningful to new users trying to learn how Molecule works.

Despite these poor docs, I went ahead and installed molecule and ran molecule --help. These docs are actually better! Here are the docs for the same two sub-commands, as output by molecule --help:

  check        Use the provisioner to perform a Dry-Run (destroy, dependency, create, prepare, converge).
  cleanup      Use the provisioner to cleanup any changes made to external systems during the stages of testing.

And if I try: molecule check --help, those docs are decent too:

molecule check --help
Usage: molecule check [OPTIONS]

  Use the provisioner to perform a Dry-Run (destroy, dependency, create,     prepare, converge).

Options:
  -s, --scenario-name TEXT    Name of the scenario to target. (default)
  --parallel / --no-parallel  Enable or disable parallel mode. Default is disabled.
  --help                      Show this message and exit.

I nearly didn't install molecule because the online docs for the commands are so bad. Either the online docs should written for an end-user to read, they should be taken down, labeled as only for developers, or they should be replaced with the output produced from the online help.

The current state is a frustrating experience that will continue to turn other new users away.

[ssbarnea]

I converted these to a discussion because the "report" is not directly actionaly.

How about just making few PRs to improve the docs, gradually? Yes, we are aware that docs sucks, but only PRs will improve the situation.