Run Sphinx in nitpick mode with warning as errors (#1707)

* Pass `-n` and `-W` for docs building with Sphinx

This allows the build to explode when we make mistakes with Sphinx
syntax. As we can see from the number of errors that this already
uncovered, that can happen a lot.

Signed-off-by: Luke Murphy <lukewm@riseup.net>

* Fix errors reported by `sphinx-build -n -W`

Signed-off-by: Luke Murphy <lukewm@riseup.net>

CONTRIBUTING.rst

@@ -115,7 +115,7 @@ contributors. Until such time that we improve the build speeds we must
 therefore ask that you please perform all of the :ref:`full_testing` testing
 steps prior to submitting a pull request.
 
-.. `continuous integration`: https://travis-ci.com/ansible/molecule
+.. _`continuous integration`: https://travis-ci.com/ansible/molecule
 
 Ansible Modules
 ===============

doc/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -n -W
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build

doc/source/ci.rst

@@ -42,7 +42,7 @@ A ``.travis.yml`` using `Tox`_ as described below.
 Gitlab CI
 ^^^^^^^^^
 
-`Gitlab`_ includes its own CI. Pipelines are usually defined in a ``.gitlab-ci.yml`` file in the top folder of a repository, to be ran on Gitlab Runners. 
+`Gitlab`_ includes its own CI. Pipelines are usually defined in a ``.gitlab-ci.yml`` file in the top folder of a repository, to be ran on Gitlab Runners.
 
 Here is an example setting up a virtualenv and testing an Ansible role via Molecule. User-level pip is cached and so is the virtual environment to save time. And this is run over a runner tagged `pip36` and `docker`, because its a minimal CentOS 7 VM installed with pip36 from IUS repository and docker.
 
@@ -241,4 +241,4 @@ You also must include the ``MOLECULE_EPHEMERAL_DIRECTORY`` variable in the
 .. _`Jenkins`: https://jenkins.io/doc/book/pipeline/jenkinsfile
 .. _`Gitlab`: https://gitlab.com
 .. _`Tox`: https://tox.readthedocs.io/en/latest
-.. _parallel functionality: https://tox.readthedocs.io/en/latest/config.html#cmdoption-tox-p
+.. _`--parallel functionality`: https://tox.readthedocs.io/en/latest/config.html#cmdoption-tox-p

doc/source/configuration.rst

@@ -313,6 +313,14 @@ configuration syntax.
 .. autoclass:: molecule.scenario.Scenario()
    :undoc-members:
 
+State
+-----
+
+An internal bookkeeping mechanism.
+
+.. autoclass:: molecule.state.State()
+  :undoc-members:
+
 Verifier
 --------
 

molecule/config.py

@@ -75,7 +75,7 @@ class Config(object):
     The directory in which the ``molecule.yml`` resides is the Scenario's
     directory.  Molecule performs most functions within this directory.
 
-    The :class:`.Config` object has instantiated Dependency_, Driver_,
+    The :class:`.Config` object instantiates Dependency_, Driver_,
     :ref:`root_lint`, Platforms_, Provisioner_, Verifier_,
     :ref:`root_scenario`, and State_ references.
     """

molecule/driver/delegated.py

@@ -90,7 +90,7 @@ class Delegated(base.Base):
             login_cmd_template: 'ssh {instance} -F /tmp/ssh-config'
             ansible_connection_options:
               ansible_connection: ssh
-              ansible_ssh_common_args -F /path/to/ssh-config
+              ansible_ssh_common_args: '-F /path/to/ssh-config'
         platforms:
           - name: instance-vagrant
 
@@ -103,9 +103,10 @@ class Delegated(base.Base):
           safe_files:
             - foo
 
-    Use localhost as molecule's target
+    And in order to use localhost as molecule's target:
 
     .. code-block:: yaml
+
         driver:
           name: delegated
           options:

molecule/driver/docker.py

@@ -132,6 +132,7 @@ class Docker(base.Base):
             - foo
 
     .. _`Docker`: https://www.docker.com
+    .. _`systemd`: https://www.freedesktop.org/wiki/Software/systemd/
     """  # noqa
 
     def __init__(self, config):

molecule/state.py

@@ -48,7 +48,8 @@ class State(object):
     serialized.
 
     State is not a top level option in Molecule's config.  It's purpose is for
-    bookkeeping, and each Config_ object has a reference to a State_ object.
+    bookkeeping, and each :class:`.Config` object has a reference to a State_
+    object.
 
     .. note::
 

tox.ini

@@ -64,7 +64,7 @@ usedevelop = false
 [testenv:doc]
 passenv = *
 commands =
-    python setup.py build_sphinx --builder=html
+    python setup.py build_sphinx -n -W --builder=html
 extras =
     docs