#282: Added a "nitpicky" mode that emits warnings for all missing references.

It is activated by the ``-n`` command-line switch or the ``nitpicky`` config value.

7 files changed, 64 insertions, 31 deletions

diff --git a/CHANGES b/CHANGES
index 5fc36540..e64ef2e6 100644
--- a/CHANGES
+++ b/CHANGES
@@ -20,6 +20,10 @@ Release 1.0 (in development)
 * New more compact doc field syntax is now recognized:
   ``:param type name: description``.
 
+* Added a "nitpicky" mode that emits warnings for all missing
+  references.  It is activated by the ``-n`` command-line switch
+  or the ``nitpicky`` config value.
+
 * Added the ``viewcode`` extension.
 
 * Added ``html-collect-pages`` event.
diff --git a/doc/config.rst b/doc/config.rst
index 21b0134d..5dbccb4e 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -206,29 +206,19 @@ General configuration
 
    .. versionadded:: 0.5
 
-.. confval:: modindex_common_prefix
-
-   A list of prefixes that are ignored for sorting the Python module index
-   (e.g., if this is set to ``['foo.']``, then ``foo.bar`` is shown under ``B``,
-   not ``F``). This can be handy if you document a project that consists of a
-   single package.  Works only for the HTML builder currently.  Default is
-   ``[]``.
-
-   .. versionadded:: 0.6
-
-.. confval:: trim_doctest_flags
+.. confval:: needs_sphinx
 
-   If true, doctest flags (comments looking like ``# doctest: FLAG, ...``) at
-   the ends of lines are removed for all code blocks showing interactive Python
-   sessions (i.e. doctests).  Default is true.  See the extension
-   :mod:`~sphinx.ext.doctest` for more possibilities of including doctests.
+   If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will
+   compare it with its version and refuse to build if it is too old.  Default is
+   no requirement.
 
    .. versionadded:: 1.0
 
-.. confval:: needs_sphinx
+.. confval:: nitpicky
 
-   If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will
-   compare it with its version and refuse to build if it is too old.
+   If true, Sphinx will warn about *all* references where the target cannot be
+   found.  Default is ``False``.  You can activate this mode temporarily using
+   the :option:`-n` command-line switch.
 
    .. versionadded:: 1.0
 
@@ -334,6 +324,16 @@ Project information
    A boolean that decides whether :dir:`moduleauthor` and :dir:`sectionauthor`
    directives produce any output in the built files.
 
+.. confval:: modindex_common_prefix
+
+   A list of prefixes that are ignored for sorting the Python module index
+   (e.g., if this is set to ``['foo.']``, then ``foo.bar`` is shown under ``B``,
+   not ``F``). This can be handy if you document a project that consists of a
+   single package.  Works only for the HTML builder currently.  Default is
+   ``[]``.
+
+   .. versionadded:: 0.6
+
 .. confval:: trim_footnote_reference_space
 
    Trim spaces before footnote references that are necessary for the reST parser
@@ -341,6 +341,15 @@ Project information
 
    .. versionadded:: 0.6
 
+.. confval:: trim_doctest_flags
+
+   If true, doctest flags (comments looking like ``# doctest: FLAG, ...``) at
+   the ends of lines are removed for all code blocks showing interactive Python
+   sessions (i.e. doctests).  Default is true.  See the extension
+   :mod:`~sphinx.ext.doctest` for more possibilities of including doctests.
+
+   .. versionadded:: 1.0
+
 
 .. _html-options:
 
diff --git a/doc/intro.rst b/doc/intro.rst
index 773bc74e..37346b6f 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -130,6 +130,10 @@ The :program:`sphinx-build` script has several more options:
 **-A** *name=value*
    Make the *name* assigned to *value* in the HTML templates.
 
+**-n**
+   Run in nit-picky mode.  Currently, this generates warnings for all missing
+   references.
+
 **-N**
    Do not do colored output.  (On Windows, colored output is disabled in any
    case.)
diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst
index ca493ec0..30f824e8 100644
--- a/doc/man/sphinx-build.rst
+++ b/doc/man/sphinx-build.rst
@@ -66,25 +66,25 @@ Options
 
 -b <builder>          Builder to use; defaults to html. See the full list
                       of builders above.
--a                    Generates output for all files; without this option only
+-a                    Generate output for all files; without this option only
                       output for new and changed files is generated.
--E                    Ignores cached files, forces to re-read all source files
+-E                    Ignore cached files, forces to re-read all source files
                       from disk.
--c <path>             Locates the conf.py file in the specified path instead of
+-c <path>             Locate the conf.py file in the specified path instead of
                       <sourcedir>.
--C                    Specifies that no conf.py file at all is to be used.
+-C                    Specify that no conf.py file at all is to be used.
                       Configuration can only be set with the -D option.
--D <setting=value>    Overrides a setting from the configuration file.
+-D <setting=value>    Override a setting from the configuration file.
 -d <path>             Path to cached files; defaults to <outdir>/.doctrees.
--A <name=value>       Passes a value into the HTML templates (only for HTML builders).
--N                    Prevents colored output.
--q                    Quiet operation, just prints warnings and errors on stderr.
--Q                    Very quiet operation, doesn't print anything except for
-                      errors.
+-A <name=value>       Pass a value into the HTML templates (only for HTML builders).
+-n                    Run in nit-picky mode, warn about all missing references.
+-N                    Prevent colored output.
+-q                    Quiet operation, just print warnings and errors on stderr.
+-Q                    Very quiet operation, don't print anything except for errors.
 -w <file>             Write warnings and errors into the given file, in addition
                       to stderr.
 -W                    Turn warnings into errors.
--P                    Runs Pdb on exception.
+-P                    Run Pdb on exception.
 
 
 See also
diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py
index bc5aff87..e3e94465 100644
--- a/sphinx/cmdline.py
+++ b/sphinx/cmdline.py
@@ -43,6 +43,7 @@ new and changed files
          -C        -- use no config file at all, only -D options
          -D <setting=value> -- override a setting in configuration
          -A <name=value>    -- pass a value into the templates, for HTML builder
+         -n        -- nit-picky mode, warn about all missing references
          -N        -- do not do colored output
          -q        -- no output on stdout, just warnings on stderr
          -Q        -- no output at all, not even warnings
@@ -61,7 +62,7 @@ def main(argv):
         nocolor()
 
     try:
-        opts, args = getopt.getopt(argv[1:], 'ab:t:d:c:CD:A:g:NEqQWw:P')
+        opts, args = getopt.getopt(argv[1:], 'ab:t:d:c:CD:A:ng:NEqQWw:P')
         allopts = set(opt[0] for opt in opts)
         srcdir = confdir = path.abspath(args[0])
         if not path.isdir(srcdir):
@@ -142,6 +143,8 @@ def main(argv):
             except ValueError:
                 pass
             confoverrides['html_context.%s' % key] = val
+        elif opt == '-n':
+            confoverrides['nitpicky'] = True
         elif opt == '-N':
             nocolor()
         elif opt == '-E':
diff --git a/sphinx/config.py b/sphinx/config.py
index 0de30a5a..24082b6c 100644
--- a/sphinx/config.py
+++ b/sphinx/config.py
@@ -62,6 +62,7 @@ class Config(object):
         trim_doctest_flags = (True, 'env'),
         default_domain = ('py', 'env'),
         needs_sphinx = (None, None),
+        nitpicky = (False, 'env'),
 
         # HTML options
         html_theme = ('default', 'html'),
diff --git a/sphinx/environment.py b/sphinx/environment.py
index c6ca8b7e..b4720ae7 100644
--- a/sphinx/environment.py
+++ b/sphinx/environment.py
@@ -1227,6 +1227,7 @@ class BuildEnvironment:
             typ = node['reftype']
             target = node['reftarget']
             refdoc = node.get('refdoc', fromdocname)
+            warned = False
 
             try:
                 if node.has_key('refdomain') and node['refdomain']:
@@ -1247,6 +1248,7 @@ class BuildEnvironment:
                         if not docname:
                             self.warn(refdoc, 'undefined label: %s' %
                                       target, node.line)
+                            warned = True
                     else:
                         # reference to named label; the final node will
                         # contain the section name after the label
@@ -1257,6 +1259,7 @@ class BuildEnvironment:
                                 'undefined label: %s' % target + ' -- if you '
                                 'don\'t give a link caption the label must '
                                 'precede a section header.', node.line)
+                            warned = True
                     if docname:
                         newnode = nodes.reference('', '')
                         innernode = nodes.emphasis(sectname, sectname)
@@ -1281,6 +1284,7 @@ class BuildEnvironment:
                     if docname not in self.all_docs:
                         self.warn(refdoc,
                                   'unknown document: %s' % docname, node.line)
+                        warned = True
                     else:
                         if node['refexplicit']:
                             # reference with explicit title
@@ -1295,8 +1299,9 @@ class BuildEnvironment:
                 elif typ == 'citation':
                     docname, labelid = self.citations.get(target, ('', ''))
                     if not docname:
-                        self.warn(node['refdoc'],
+                        self.warn(refdoc,
                                   'citation not found: %s' % target, node.line)
+                        warned = True
                     else:
                         newnode = make_refnode(builder, fromdocname, docname,
                                                labelid, contnode)
@@ -1317,6 +1322,13 @@ class BuildEnvironment:
                 if newnode is None:
                     newnode = builder.app.emit_firstresult(
                         'missing-reference', self, node, contnode)
+                    # still not found? warn if in nit-picky mode
+                    if newnode is None and not warned and self.config.nitpicky:
+                        self.warn(refdoc,
+                            'reference target not found: %stype %s, target %s'
+                            % (node.get('refdomain') and
+                               'domain %s, ' % node['refdomain'] or '',
+                               typ, target))
             except NoUri:
                 newnode = contnode
             node.replace_self(newnode or contnode)