Georg Brandl avatar Georg Brandl committed c67f32d

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

Comments (0)

Files changed (7)

 * 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.
 
    .. versionadded:: 0.5
 
-.. confval:: modindex_common_prefix
+.. confval:: needs_sphinx
 
-   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
-
-   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
 
    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
 
    .. 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:
 
 **-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.)

doc/man/sphinx-build.rst

 
 -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

sphinx/cmdline.py

          -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
         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):
             except ValueError:
                 pass
             confoverrides['html_context.%s' % key] = val
+        elif opt == '-n':
+            confoverrides['nitpicky'] = True
         elif opt == '-N':
             nocolor()
         elif opt == '-E':
         trim_doctest_flags = (True, 'env'),
         default_domain = ('py', 'env'),
         needs_sphinx = (None, None),
+        nitpicky = (False, 'env'),
 
         # HTML options
         html_theme = ('default', 'html'),

sphinx/environment.py

             typ = node['reftype']
             target = node['reftarget']
             refdoc = node.get('refdoc', fromdocname)
+            warned = False
 
             try:
                 if node.has_key('refdomain') and node['refdomain']:
                         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
                                 '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)
                     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
                 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)
                 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)
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.