Add a test to ensure all rst ini blocks parse correctly (#901)

doc/config.rst

@@ -17,13 +17,20 @@ List of optional global options:
 .. code-block:: ini
 
     [tox]
-    minversion=ver    # minimally required tox version
-    toxworkdir=path   # tox working directory, defaults to {toxinidir}/.tox
-    setupdir=path     # defaults to {toxinidir}
-    distdir=path      # defaults to {toxworkdir}/dist
-    distshare=path    # (DEPRECATED) defaults to {homedir}/.tox/distshare
-    envlist=ENVLIST   # defaults to the list of all environments
-    skipsdist=BOOL    # defaults to false
+    # minimally required tox version
+    minversion=ver
+    # tox working directory, defaults to {toxinidir}/.tox
+    toxworkdir=path
+    # defaults to {toxinidir}
+    setupdir=path
+    # defaults to {toxworkdir}/dist
+    distdir=path
+    # (DEPRECATED) defaults to {homedir}/.tox/distshare
+    distshare=path
+    # defaults to the list of all environments
+    envlist=ENVLIST
+    # bool: defaults to False
+    skipsdist=False
 
 
 ``tox`` autodetects if it is running in a Jenkins_ context
@@ -33,7 +40,7 @@ and will first lookup global tox settings in this section:
 .. code-block:: ini
 
     [tox:jenkins]
-    ...               # override [tox] settings for the jenkins context
+    commands = ...  # override [tox] settings for the jenkins context
     # note: for jenkins distshare defaults to ``{toxworkdir}/distshare`` (DEPRECATED)
 
 .. confval:: skip_missing_interpreters=BOOL
@@ -79,13 +86,13 @@ Test environments are defined by a:
 .. code-block:: ini
 
     [testenv:NAME]
-    ...
+    commands = ...
 
 section.  The ``NAME`` will be the name of the virtual environment.
 Defaults for each setting in this section are looked up in the::
 
     [testenv]
-    ...
+    commands = ...
 
 testenvironment default section.
 
@@ -216,6 +223,11 @@ Complete list of settings that you can put into ``testenv*`` sections:
 
     .. code-block:: ini
 
+        [tox]
+        indexserver =
+            myindexserver = https://myindexserver.example.com/simple
+
+        [testenv]
         deps = :myindexserver:pkg
 
     (Experimentally introduced in 1.6.1) all installer commands are executed
@@ -242,6 +254,7 @@ Complete list of settings that you can put into ``testenv*`` sections:
 
     .. code-block:: ini
 
+        [testenv]
         setenv   =
             PYTHONPATH = {env:PYTHONPATH}{:}{toxinidir}
 
@@ -746,7 +759,7 @@ For example:
 
     [testenv:py27]
     deps =
-        {{[testenv]deps}}
+        {[testenv]deps}
         pytest
 
 With the previous configuration, it will install:

doc/example/basic.rst

@@ -65,6 +65,7 @@ runs on you can set a platform regular expression like this:
 
 .. code-block:: ini
 
+    [testenv]
     platform = linux2|darwin
 
 If the expression does not match against ``sys.platform``
@@ -101,18 +102,21 @@ depending on requirements.txt or defining constraints
 
 .. code-block:: ini
 
+    [testenv]
     deps = -rrequirements.txt
 
 or
 
 .. code-block:: ini
 
+    [testenv]
     deps = -cconstraints.txt
 
 or
 
 .. code-block:: ini
 
+    [testenv]
     deps = -rrequirements.txt -cconstraints.txt
 
 All installation commands are executed using ``{toxinidir}`` (the directory where ``tox.ini`` resides) as the current working directory.

doc/example/devenv.rst

@@ -47,6 +47,7 @@ configuration:
 
 .. code-block:: ini
 
+    [testenv:devenv]
     commands =
     deps =
 

doc/example/general.rst

@@ -18,13 +18,14 @@ test commands, for example using ``pytest``:
 
 .. code-block:: ini
 
-    # in the testenv or testenv:NAME section of your tox.ini
+    [testenv]  # or testenv:NAME section of your tox.ini
     commands = pytest {posargs}
 
 or using ``nosetests``:
 
 .. code-block:: ini
 
+    [testenv]
     commands = nosetests {posargs}
 
 the above ``tox`` invocation will trigger the test runners to
@@ -35,6 +36,7 @@ syntax:
 
 .. code-block:: ini
 
+    [testenv]
     commands = nosetests {posargs:--with-coverage}
 
 .. _`sphinx checks`:

doc/example/jenkins.rst

@@ -37,6 +37,7 @@ for example with ``pytest`` it is done like this:
 
 .. code-block:: ini
 
+    [testenv]
     commands = pytest --junitxml=junit-{envname}.xml
 
 

src/tox/config.py

@@ -1193,7 +1193,9 @@ def getbool(self, name, default=None, replace=True):
             elif s.lower() == "false":
                 s = False
             else:
-                raise tox.exception.ConfigError("boolean value %r needs to be 'True' or 'False'")
+                raise tox.exception.ConfigError(
+                    "{}: boolean value {!r} needs to be 'True' or 'False'".format(name, s)
+                )
         return s
 
     def getargvlist(self, name, default="", replace=True):

tests/test_config.py

@@ -807,8 +807,10 @@ def test_getbool(self, newconfig):
         assert reader.getbool("key2a") is False
         with pytest.raises(KeyError):
             reader.getbool("key3")
-        with pytest.raises(tox.exception.ConfigError):
+        with pytest.raises(tox.exception.ConfigError) as excinfo:
             reader.getbool("key5")
+        msg, = excinfo.value.args
+        assert msg == "key5: boolean value 'yes' needs to be 'True' or 'False'"
 
 
 class TestIniParserPrefix:

tests/test_docs.py

@@ -0,0 +1,53 @@
+import os.path
+import re
+import textwrap
+
+import pytest
+
+from tox.config import parseconfig
+
+INI_BLOCK_RE = re.compile(
+    r"(?P<before>"
+    r"^(?P<indent> *)\.\. (code-block|sourcecode):: ini\n"
+    r"((?P=indent) +:.*\n)*"
+    r"\n*"
+    r")"
+    r"(?P<code>(^((?P=indent) +.*)?\n)+)",
+    re.MULTILINE,
+)
+
+
+RST_FILES = []
+TOX_ROOT = os.path.join(os.path.dirname(os.path.dirname(__file__)))
+for root, _, filenames in os.walk(os.path.join(TOX_ROOT, "doc")):
+    for f in filenames:
+        if f.endswith(".rst"):
+            RST_FILES.append(os.path.join(root, f))
+
+
+def test_some_files_exist():
+    assert RST_FILES
+
+
+@pytest.mark.parametrize("filename", RST_FILES)
+def test_all_rst_ini_blocks_parse(filename, tmpdir):
+    with open(filename) as f:
+        contents = f.read()
+    for match in INI_BLOCK_RE.finditer(contents):
+        code = textwrap.dedent(match.group("code"))
+        f = tmpdir.join("tox.ini")
+        f.write(code)
+        try:
+            parseconfig(("-c", str(f)))
+        except Exception as e:
+            raise AssertionError(
+                "Error parsing ini block\n\n"
+                "{filename}:{lineno}\n\n"
+                "{code}\n\n"
+                "{error}\n\n{error!r}".format(
+                    filename=filename,
+                    lineno=contents[: match.start()].count("\n") + 1,
+                    code="\t" + code.replace("\n", "\n\t").strip(),
+                    error=e,
+                )
+            )