#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.

3 files changed, 42 insertions, 29 deletions

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