Add some known Sphinx roles and directives

.travis.yml

@@ -36,6 +36,7 @@ script:
  - flake8 --select RST setup.py flake8_rst_docstrings.py
  - echo "Checking we can parse our valid test cases"
  - flake8 --select RST --ignore RST303,RST304 tests/test_cases/*.py
+ - flake8 --select RST tests/test_cases/sphinx-py.py
 
 notifications:
   email: false

README.rst

@@ -181,7 +181,10 @@ v0.0.7  2017-08-25 - Remove triple-quotes before linting, was causing false
                      positives reporting RST entries ending without a blank
                      line at end of docstrings (bug fix for issue #1).
 v0.0.8  2017-10-09 - Adds ``RST303`` and ``RST304`` for unknown directives and
-                     interpreted text role as used in Sphinx-Needs extension.
+                     interpreted text role, used heavily in Sphinx.
+v0.0.9  *pending*  - Will not raise ``RST303`` and ``RST304`` for a hard coded
+                     list of Sphinx roles and directives from ``std``, ``rst``
+                     and ``py`` domains (e.g. ``:py:class:`` or ``:class:``).
 ======= ========== ===========================================================
 
 

flake8_rst_docstrings.py

@@ -139,7 +139,7 @@ def tokenize_open(filename):
 import restructuredtext_lint as rst_lint
 
 
-__version__ = "0.0.8"
+__version__ = "0.0.9"
 
 
 log = logging.getLogger(__name__)
@@ -182,6 +182,112 @@ def tokenize_open(filename):
     "Unknown interpreted text role": 4,
 }
 
+# RST303 Unknown directive type "XXX".
+# RST304 Unknown interpreted text role "XXX".
+#
+# These default lists are from Sphinx 1.6.6, determined as follows:
+#
+# from sphinx.application import Sphinx
+# s = Sphinx('.', None, '.', '.', 'html')
+# print("known_directives = set([")
+# for d in ('py', 'rst', 'std'):
+#     for dir in sorted(s.registry.domains[d].directives):
+#         print("    %r, %r," % (d + ':' + dir, dir))
+# print("])")
+# print("known_roles = set([")
+# for d in ('py', 'rst', 'std'):
+#     for role in sorted(s.registry.domains[d].roles):
+#         print("    %r, %r," % (d + ':' + role, role))
+# print("])")
+#
+known_directives = set(
+    [
+        "py:attribute",
+        "attribute",
+        "py:class",
+        "class",
+        "py:classmethod",
+        "classmethod",
+        "py:currentmodule",
+        "currentmodule",
+        "py:data",
+        "data",
+        "py:decorator",
+        "decorator",
+        "py:decoratormethod",
+        "decoratormethod",
+        "py:exception",
+        "exception",
+        "py:function",
+        "function",
+        "py:method",
+        "method",
+        "py:module",
+        "module",
+        "py:staticmethod",
+        "staticmethod",
+        "rst:directive",
+        "directive",
+        "rst:role",
+        "role",
+        "std:cmdoption",
+        "cmdoption",
+        "std:envvar",
+        "envvar",
+        "std:glossary",
+        "glossary",
+        "std:option",
+        "option",
+        "std:productionlist",
+        "productionlist",
+        "std:program",
+        "program",
+    ]
+)
+
+known_roles = set(
+    [
+        "py:attr",
+        "attr",
+        "py:class",
+        "class",
+        "py:const",
+        "const",
+        "py:data",
+        "data",
+        "py:exc",
+        "exc",
+        "py:func",
+        "func",
+        "py:meth",
+        "meth",
+        "py:mod",
+        "mod",
+        "py:obj",
+        "obj",
+        "rst:dir",
+        "dir",
+        "rst:role",
+        "role",
+        "std:doc",
+        "doc",
+        "std:envvar",
+        "envvar",
+        "std:keyword",
+        "keyword",
+        "std:numref",
+        "numref",
+        "std:option",
+        "option",
+        "std:ref",
+        "ref",
+        "std:term",
+        "term",
+        "std:token",
+        "token",
+    ]
+)
+
 # Level 4 - severe
 code_mapping_severe = {"Unexpected section title.": 1}
 
@@ -207,6 +313,11 @@ def code_mapping(level, msg, default=99):
     # ---> 'Unknown interpreted text role'
     if msg.count('"') == 2 and ' "' in msg and msg.endswith('".'):
         txt = msg[: msg.index(' "')]
+        value = msg.split('"', 2)[1]
+        if txt == "Unknown directive type" and value in known_directives:
+            return 0
+        if txt == "Unknown interpreted text role" and value in known_roles:
+            return 0
         return code_mappings_by_level[level].get(txt, default)
     return default
 
@@ -1039,7 +1150,10 @@ def run(self):
                 # Map the string to a unique code:
                 msg = rst_error.message.split("\n", 1)[0]
                 code = code_mapping(rst_error.level, msg)
-                assert code < 100, code
+                if not code:
+                    # We ignored it, e.g. a known Sphinx role
+                    continue
+                assert 0 < code < 100, code
                 code += 100 * rst_error.level
                 msg = "%s%03i %s" % (rst_prefix, code, msg)
 

tests/test_cases/sphinx-py.py

@@ -0,0 +1,39 @@
+"""Module description here.
+
+This is an example from the Sphinx documentation, although
+I'm not sure how one might put it into the function's docstring,
+the point here is to use a Sphinx directive:
+
+.. py:function:: send_message(sender, recipient, message_body, [priority=1])
+
+   Send a message to a recipient
+
+   :param str sender: The person sending the message
+   :param str recipient: The recipient of the message
+   :param str message_body: The body of the message
+   :param priority: The priority of the message, can be a number 1-5
+   :type priority: integer or None
+   :return: the message id
+   :rtype: int
+   :raises ValueError: if the message_body exceeds 160 characters
+   :raises TypeError: if the message_body is not a basestring
+
+The end.
+"""
+
+
+class X(object):
+    """This is :class:`X` which is an example.
+
+    Can also include the Python namespace in the Sphinx
+    notation :py:class:`X` as well.
+
+    The point of this test is to check we don't get::
+
+        RST304 Unknown interpreted text role "class".
+        RST304 Unknown interpreted text role "py:class".
+
+    This is because these are now on the default list of roles.
+    """
+
+    pass