Add a sphinx specific mode

When doc8 scans rst files with sphinx specific roles
and references it is unable to determine what those roles
are and then complains that these false positives are
actual errors.

To avoid these types of false positives add a option that
can be provided when running on files that may contain these
types of errors to allow them to be skipped/ignored.

Change-Id: Ia6896617534f68e517d5996d53cf2de274507f56

README.rst

@@ -54,6 +54,7 @@ Usage
                             pep8.ini, setup.cfg)
       --allow-long-titles   allow long section titles (default: False)
       --ignore code         ignore the given errors code/codes
+      --no-sphinx           do not ignore sphinx specific false positives
       --ignore-path path
                             ignore the given directory or file
       --max-line-length int

doc8/checks.py

@@ -76,13 +76,32 @@ class CheckCarriageReturn(LineCheck):
 class CheckValidity(ContentCheck):
     REPORTS = frozenset(["D000"])
 
+    # Only used when running in sphinx mode.
+    SPHINX_PREFIX_IGNORES = [
+        'Unknown interpreted text',
+        'Unknown directive type',
+        'Undefined substitution',
+        'Substitution definition contains illegal element',
+    ]
+
+    def __init__(self, cfg):
+        super(CheckValidity, self).__init__(cfg)
+        self._sphinx_mode = cfg.get('sphinx')
+
     def report_iter(self, parsed_file):
         for error in parsed_file.errors:
             if error.line is None:
                 continue
             if error.level <= 1:
                 continue
-            yield (error.line, 'D000', error.message)
+            ignore = False
+            if self._sphinx_mode:
+                for m in self.SPHINX_PREFIX_IGNORES:
+                    if error.message.startswith(m):
+                        ignore = True
+                        break
+            if not ignore:
+                yield (error.line, 'D000', error.message)
 
 
 class CheckMaxLineLength(ContentCheck):

doc8/main.py

@@ -93,6 +93,10 @@ def extract_config(args):
                                                      "allow-long-titles")
     except (configparser.NoSectionError, configparser.NoOptionError):
         pass
+    try:
+        cfg['sphinx'] = parser.getboolean("doc8", "sphinx")
+    except (configparser.NoSectionError, configparser.NoOptionError):
+        pass
     try:
         extensions = parser.get("doc8", "extensions")
         extensions = extensions.split(",")
@@ -144,6 +148,9 @@ def main():
                         help="ignore the given errors code/codes",
                         type=split_set_type,
                         default=[])
+    parser.add_argument("--no-sphinx", action="store_false",
+                        help="do not ignore sphinx specific false positives",
+                        default=True)
     parser.add_argument("--ignore-path", action="append", default=[],
                         help="ignore the given directory or file",
                         metavar='path')
@@ -161,6 +168,8 @@ def main():
     args['ignore'] = merge_sets(args['ignore'])
     cfg = extract_config(args)
     args['ignore'].update(cfg.pop("ignore", set()))
+    if 'sphinx' in cfg:
+        args['sphinx'] = cfg.pop("sphinx")
     args['extension'].extend(cfg.pop('extension', []))
     args.update(cfg)
     if not args.get('extension'):