IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
It is activated by the ``-n`` command-line switch or the ``nitpicky`` config value.
This commit is contained in:
Georg Brandl 2010-02-28 12:13:55 +01:00
parent ea8fa8aa02
commit 3d01c2c95f
7 changed files with 66 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
CHANGES
View File

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

49
doc/config.rst
View File

@ -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
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
.. confval:: needs_sphinx
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.
compare it with its version and refuse to build if it is too old. Default is
no requirement.
.. versionadded:: 1.0
.. confval:: nitpicky
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:

4
doc/intro.rst
View File

@ -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.)

22
doc/man/sphinx-build.rst
View File

@ -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

5
sphinx/cmdline.py
View File

@ -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':

1
sphinx/config.py
View File

@ -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'),

14
sphinx/environment.py
View File

@ -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)