Add rstcheck to ansible-test and correct issues. (#23550)

* Add rstcheck to ansible-test.
* Fix rst code-block languages and syntax errors.
* Fix rst inline literals.
* Update python 2 code block to pass tests on py 3.

docs/docsite/rst/dev_guide/developing_modules_best_practices.rst

@@ -171,7 +171,7 @@ You should never do this in a module:
 
 .. code-block:: python
 
-    print "some status message"
+    print("some status message")
 
 Because the output is supposed to be valid JSON.
 

docs/docsite/rst/dev_guide/developing_python3.rst

@@ -130,6 +130,7 @@ to yield text but instead do the conversion explicitly ourselves. For example:
             # Handle the exception gracefully -- usually by displaying a good
             # user-centric error message that can be traced back to this piece
             # of code.
+            pass
 
 .. note:: Much of Ansible assumes that all encoded text is UTF-8.  At some
     point, if there is demand for other encodings we may change that, but for
@@ -293,7 +294,8 @@ new exception-catching syntax which uses the ``as`` keyword:
 
 Do **not** use the following syntax as it will fail on every version of Python-3:
 
-.. code-block:: python
+.. This code block won't highlight because python2 isn't recognized. This is necessary to pass tests under python 3.
+.. code-block:: python2
 
     try:
         a = 2/0
@@ -399,7 +401,6 @@ Python-2 and Python-3.  You may still see this used in some modules:
 .. code-block:: python
 
     from ansible.module_utils.pycompat24 import get_exception
-    [...]
 
     try:
         a = 2/0

docs/docsite/rst/dev_guide/developing_test_pr.rst

@@ -185,11 +185,11 @@ If the PR does not resolve the issue, or if you see any failures from the unit/i
    |
    | When I ran this Ubuntu 16.04 it failed with the following:
    |
-   |   ```
+   |   \```
    |   BLARG
    |   StrackTrace
    |   RRRARRGGG
-   |   ```
+   |   \```
 
 When you are done testing a feature branch, you can remove it with the following command:
 

docs/docsite/rst/intro_windows.rst

@@ -107,13 +107,13 @@ Edit your /etc/krb5.conf (which should be installed as a result of installing pa
 
 In the section that starts with
 
-.. code-block:: bash
+.. code-block:: ini
 
    [realms]
 
 add the full domain name and the fully qualified domain names of your primary and secondary Active Directory domain controllers.  It should look something like this:
 
-.. code-block:: bash
+.. code-block:: ini
 
    [realms]
    
@@ -125,7 +125,7 @@ add the full domain name and the fully qualified domain names of your primary an
 
 and in the [domain_realm] section add a line like the following for each domain you want to access:
 
-.. code-block:: bash
+.. code-block:: ini
 
     [domain_realm]
         .my.domain.com = MY.DOMAIN.COM

docs/docsite/rst/network_debug_troubleshooting.rst

@@ -151,7 +151,7 @@ talk to the remote network device. This generally means that there is an authent
 
 For example:
 
-.. code-block::
+.. code-block:: none
 
   TASK [prepare_eos_tests : enable cli on remote device] **************************************************
   fatal: [veos01]: FAILED! => {"changed": false, "failed": true, "msg": "unable to open shell"}
@@ -160,7 +160,7 @@ For example:
 or:
 
 
-.. code-block:: yaml
+.. code-block:: none
 
    TASK [ios_system : configure name_servers] *************************************************************
    task path:

test/runner/lib/sanity.py

@@ -18,6 +18,7 @@ from lib.util import (
     display,
     run_command,
     deepest_path,
+    parse_to_dict,
 )
 
 from lib.ansible_util import (
@@ -566,6 +567,60 @@ def command_sanity_yamllint(args, targets):
     return SanitySuccess(test)
 
 
+def command_sanity_rstcheck(args, targets):
+    """
+    :type args: SanityConfig
+    :type targets: SanityTargets
+    :rtype: SanityResult
+    """
+    test = 'rstcheck'
+
+    with open('test/sanity/rstcheck/ignore-substitutions.txt', 'r') as ignore_fd:
+        ignore_substitutions = sorted(set(ignore_fd.read().splitlines()))
+
+    paths = sorted(i.path for i in targets.include if os.path.splitext(i.path)[1] in ('.rst',))
+
+    if not paths:
+        return SanitySkipped(test)
+
+    cmd = [
+        'rstcheck',
+        '--report', 'warning',
+        '--ignore-substitutions', ','.join(ignore_substitutions),
+    ] + paths
+
+    try:
+        stdout, stderr = run_command(args, cmd, capture=True)
+        status = 0
+    except SubprocessError as ex:
+        stdout = ex.stdout
+        stderr = ex.stderr
+        status = ex.status
+
+    if stdout:
+        raise SubprocessError(cmd=cmd, status=status, stderr=stderr, stdout=stdout)
+
+    if args.explain:
+        return SanitySkipped(test)
+
+    pattern = r'^(?P<path>[^:]*):(?P<line>[0-9]+): \((?P<level>INFO|WARNING|ERROR|SEVERE)/[0-4]\) (?P<message>.*)$'
+
+    results = [parse_to_dict(pattern, line) for line in stderr.splitlines()]
+
+    results = [SanityMessage(
+        message=r['message'],
+        path=r['path'],
+        line=int(r['line']),
+        column=0,
+        level=r['level'],
+    ) for r in results]
+
+    if results:
+        return SanityFailure(test, messages=results)
+
+    return SanitySuccess(test)
+
+
 def command_sanity_ansible_doc(args, targets, python_version):
     """
     :type args: SanityConfig
@@ -729,6 +784,7 @@ SANITY_TESTS = (
     SanityFunc('pep8', command_sanity_pep8, intercept=False),
     SanityFunc('pylint', command_sanity_pylint, intercept=False),
     SanityFunc('yamllint', command_sanity_yamllint, intercept=False),
+    SanityFunc('rstcheck', command_sanity_rstcheck, intercept=False),
     SanityFunc('validate-modules', command_sanity_validate_modules, intercept=False),
     SanityFunc('ansible-doc', command_sanity_ansible_doc),
 )

test/runner/lib/util.py

@@ -7,6 +7,7 @@ import os
 import pipes
 import shutil
 import subprocess
+import re
 import sys
 import time
 
@@ -495,4 +496,18 @@ def docker_qualify_image(name):
     return 'ansible/ansible:%s' % name
 
 
+def parse_to_dict(pattern, value):
+    """
+    :type pattern: str
+    :type value: str
+    :return: dict[str, str]
+    """
+    match = re.search(pattern, value)
+
+    if match is None:
+        raise Exception('Pattern "%s" did not match value: %s' % (pattern, value))
+
+    return match.groupdict()
+
+
 display = Display()  # pylint: disable=locally-disabled, invalid-name

test/runner/requirements/sanity.txt

@@ -3,5 +3,7 @@ mock
 pep8
 pylint
 pytest
+rstcheck
+sphinx
 voluptuous
 yamllint

test/sanity/rstcheck/ignore-substitutions.txt

@@ -0,0 +1,2 @@
+version
+versiondev