Documentation: fixing --parallel flag position and typos (#2858)

Fixing the --parallel flag position in the CLI reference and fixing typos.
Also adding a line about running Molecule in parallel with other tools.

Signed-off-by: Arnaud SINAYS <[email protected]>

Author: Arnoways

docs/ci.rst

@@ -328,7 +328,7 @@ we export a ``TOX_ENVNAME`` environment variable, it's the name of our tox env.
 
 
 You also must include the ``TOX_ENVNAME`` variable in name of each platform in
-``molecule.yml`` configuration file. This way, ther names won't create any
+``molecule.yml`` configuration file. This way, their names won't create any
 conflict.
 
 .. code-block:: yaml

docs/examples.rst

@@ -216,7 +216,7 @@ When needed, such security profiles can be reused (for example `the one availabl
           - /sys/fs/cgroup:/sys/fs/cgroup:ro
 
 The developer can also opt to `start the container with extended privileges`_,
-by either giving it ``SYS_ADMIN`` capabilites or running it in ``privileged`` mode.
+by either giving it ``SYS_ADMIN`` capabilities or running it in ``privileged`` mode.
 
 .. important::
 
@@ -385,9 +385,6 @@ Running Molecule processes in parallel mode
 
     It is currently only available for use with the Docker driver.
 
-It is possible to run Molecule processes in parallel using another tool to
-orchestrate the parallelization (such as `GNU Parallel`_ or `Pytest`_).
-
 When Molecule receives the ``--parallel`` flag it will generate a `UUID`_ for
 the duration of the testing sequence and will use that unique identifier to
 cache the run-time state for that process. The parallel Molecule processes
@@ -398,6 +395,12 @@ Molecule uses a new and separate caching folder for this in the
 ``$HOME/.cache/molecule_parallel`` location. Molecule exposes a new environment
 variable ``MOLECULE_PARALLEL`` which can enable this functionality.
 
+It is possible to run Molecule processes in parallel using another tool to
+orchestrate the parallelization (such as `GNU Parallel`_ or `Pytest`_).
+If you do so, make sure Molecule knows it is running in parallel mode by
+specifying the ``--parallel`` flag to your command(s) to avoid concurrency
+issues.
+
 .. _GNU Parallel: https://www.gnu.org/software/parallel/
 .. _Pytest: https://docs.pytest.org/en/latest/
 .. _UUID: https://en.wikipedia.org/wiki/Universally_unique_identifier

molecule/command/check.py

@@ -65,9 +65,9 @@ class Check(base.Base):
         Load an env file to read variables from when rendering
         molecule.yml.
 
-    .. program:: molecule --parallel check
+    .. program:: molecule check --parallel
 
-    .. option:: molecule --parallel check
+    .. option:: molecule check --parallel
 
        Run in parallelizable mode.
     """

molecule/command/destroy.py

@@ -79,9 +79,9 @@ class Destroy(base.Base):
         Load an env file to read variables from when rendering
         molecule.yml.
 
-    .. program:: molecule --parallel destroy
+    .. program:: molecule destroy --parallel
 
-    .. option:: molecule --parallel destroy
+    .. option:: molecule destroy --parallel
 
        Run in parallelizable mode.
     """

molecule/command/test.py

@@ -79,9 +79,9 @@ class Test(base.Base):
         Load an env file to read variables from when rendering
         molecule.yml.
 
-    .. program:: molecule --parallel test
+    .. program:: molecule test --parallel
 
-    .. option:: molecule --parallel test
+    .. option:: molecule test --parallel
 
        Run in parallelizable mode.
     """