Molecule: Molecule 3.0 worthy documentation

[decentral1se]

I'm going to use this as an umbrella issue for my work on improving docs for 3.0.

[ssbarnea]

Title is enough. I will assure we do not release 3.0 without having documentation for it.

[decentral1se]

Take note of https://github.com/ansible/molecule/issues/2079#issue-450221302:

from the docs: "converge":
"Converge will execute the sequence necessary to converge the instances."

I simply don't understand what that means. I'm trying to figure out the difference between "test", "converge", etc but it's hard. Improved docs would be awesome.

[decentral1se]

Take note of https://github.com/ansible/molecule/issues/1620:

I had tried posting this in the mailing list, but I had gotten an error about not being able to send an email out to the group(?). If this is not the appropriate channel feel free to delete this.

I am just picking up on Molecule and I am a bit confused with the commands available in Molecule.

Could someone help to clarify to me what is do these command actual do?

• molecule converge - It says to "converge the instances". When I actually ran it, it will do all the instance creation and preparation but not test. So my understanding is that this command will do all the sequences to prepare the test environment BUT not actually test anything?
• molecule test / verify - What is the difference between molecule test and molecule verify? Seems to be "verify" does the actual work of running my tests. Does "molecule test" simply test that the molecule configs can be read?

The one issue I am also having is the documentation on molecule.readthedocs.com is a bit sparse on each command

Example on 'Check' - https://molecule.readthedocs.io/en/2.19/usage.html
There is no description of what will it do. What is the difference of Check compared to Test and Verify?

It would be good if there would be expanded documentation on what each command is meant to do and what they do in detail. I can help add this if I know this myself.

[decentral1se]

See https://github.com/ansible/molecule/pull/2329#issuecomment-546722485.

[decentral1se]

See https://github.com/ansible/molecule/issues/2426#issuecomment-549329846.

[ssbarnea]

Thansk for working on this! This may become the best feature of molecule 3.0! A documentation that makes sense. Collecting user feedback is key in order to identify what we need change, document or both.

[decentral1se]

Also, remember https://github.com/ansible/molecule/issues/2441#issuecomment-554590740.

[decentral1se]

Plugin loading requries that the driver module be called "driver". See https://github.com/pycontribs/molecule-azure/blob/master/molecule_azure/driver.py. Otherwise, it will not be picked up.

[decentral1se]

FYI: I won't be pursuing this anymore.