[Python-checkins] r65631 - in doctools/trunk: CHANGES doc/config.rst sphinx/config.py sphinx/environment.py tests/root/conf.py
georg.brandl
python-checkins at python.org
Sun Aug 10 19:10:31 CEST 2008
Author: georg.brandl
Date: Sun Aug 10 19:10:31 2008
New Revision: 65631
Log:
New config value "keep_warnings", default is to discard the from the saved doctrees.
Modified:
doctools/trunk/CHANGES
doctools/trunk/doc/config.rst
doctools/trunk/sphinx/config.py
doctools/trunk/sphinx/environment.py
doctools/trunk/tests/root/conf.py
Modified: doctools/trunk/CHANGES
==============================================================================
--- doctools/trunk/CHANGES (original)
+++ doctools/trunk/CHANGES Sun Aug 10 19:10:31 2008
@@ -22,6 +22,10 @@
have Sphinx documentation, which will build the docs and place them
in the standard distutils build directory.
+* "System Message" warnings are now automatically removed from the
+ built documentation, and only written to stderr. If you want the
+ old behavior, set the new config value ``keep_warnings`` to True.
+
* ``SerializingHTMLBuilder`` was added as new abstract builder that
can be subclassed to serialize build HTML in a specific format.
The ``PickleHTMLBuilder`` is a concrete subclass of it that uses
Modified: doctools/trunk/doc/config.rst
==============================================================================
--- doctools/trunk/doc/config.rst (original)
+++ doctools/trunk/doc/config.rst Sun Aug 10 19:10:31 2008
@@ -74,6 +74,79 @@
The document name of the "master" document, that is, the document that
contains the root :dir:`toctree` directive. Default is ``'contents'``.
+.. confval:: unused_docs
+
+ A list of document names that are present, but not currently included in the
+ toctree. Use this setting to suppress the warning that is normally emitted
+ in that case.
+
+.. confval:: exclude_dirs
+
+ A list of directory names, relative to the source directory, that are to be
+ excluded from the search for source files.
+
+ .. versionadded:: 0.3
+
+.. confval:: exclude_trees
+
+ A list of directory names, relative to the source directory, that are to be
+ recursively exlucded from the search for source files, that is, their
+ subdirectories won't be searched too.
+
+ .. versionadded:: 0.4
+
+.. confval:: locale_dirs
+
+ .. versionadded:: 0.5
+
+ Directories in which to search for additional Sphinx message catalogs (see
+ :confval:`language`), relative to the source directory. The directories on
+ this path are searched by the standard :mod:`gettext` module for a domain of
+ ``sphinx``; so if you add the directory :file:`./locale` to this settting,
+ the message catalogs must be in
+ :file:`./locale/{language}/LC_MESSAGES/sphinx.mo`.
+
+ The default is ``[]``.
+
+.. confval:: templates_path
+
+ A list of paths that contain extra templates (or templates that overwrite
+ builtin templates). Relative paths are taken as relative to the
+ configuration directory.
+
+.. confval:: template_bridge
+
+ A string with the fully-qualified name of a callable (or simply a class) that
+ returns an instance of :class:`~sphinx.application.TemplateBridge`. This
+ instance is then used to render HTML documents, and possibly the output of
+ other builders (currently the changes builder).
+
+.. confval:: default_role
+
+ The name of a reST role (builtin or Sphinx extension) to use as the default
+ role, that is, for text marked up ```like this```. This can be set to
+ ``'obj'`` to make ```filter``` a cross-reference to the function "filter".
+ The default is ``None``, which doesn't reassign the default role.
+
+ The default role can always be set within individual documents using the
+ standard reST :dir:`default-role` directive.
+
+ .. versionadded:: 0.4
+
+.. confval:: keep_warnings
+
+ If true, keep warnings as "system message" paragraphs in the built documents.
+ Regardless of this setting, warnings are always written to the standard error
+ stream when ``sphinx-build`` is run.
+
+ The default is ``False``, the pre-0.5 behavior was to always keep them.
+
+ .. versionadded:: 0.5
+
+
+Project information
+-------------------
+
.. confval:: project
The documented project's name.
@@ -112,18 +185,6 @@
* ``en`` -- English
* ``fr`` -- French
-.. confval:: locale_dirs
-
- .. versionadded:: 0.5
-
- Additional directories to search for Sphinx message catalogs, relative to the
- source directory. The directories on this path are searched by the standard
- :mod:`gettext` module for a domain of ``sphinx``; so if you add the directory
- :file:`./locale` to this settting, the message catalogs must be in
- :file:`./locale/{language}/LC_MESSAGES/sphinx.mo`.
-
- The default is ``[]``.
-
.. confval:: today
today_fmt
@@ -138,27 +199,6 @@
%Y'`` (or, if translation is enabled with :confval:`language`, am equivalent
%format for the selected locale).
-.. confval:: unused_docs
-
- A list of document names that are present, but not currently included in the
- toctree. Use this setting to suppress the warning that is normally emitted
- in that case.
-
-.. confval:: exclude_dirs
-
- A list of directory names, relative to the source directory, that are to be
- excluded from the search for source files.
-
- .. versionadded:: 0.3
-
-.. confval:: exclude_trees
-
- A list of directory names, relative to the source directory, that are to be
- recursively exlucded from the search for source files, that is, their
- subdirectories won't be searched too.
-
- .. versionadded:: 0.4
-
.. confval:: pygments_style
The style name to use for Pygments highlighting of source code. Default is
@@ -169,31 +209,6 @@
If the value is a fully-qualified name of a custom Pygments style class,
this is then used as custom style.
-.. confval:: templates_path
-
- A list of paths that contain extra templates (or templates that overwrite
- builtin templates). Relative paths are taken as relative to the
- configuration directory.
-
-.. confval:: template_bridge
-
- A string with the fully-qualified name of a callable (or simply a class) that
- returns an instance of :class:`~sphinx.application.TemplateBridge`. This
- instance is then used to render HTML documents, and possibly the output of
- other builders (currently the changes builder).
-
-.. confval:: default_role
-
- The name of a reST role (builtin or Sphinx extension) to use as the default
- role, that is, for text marked up ```like this```. This can be set to
- ``'obj'`` to make ```filter``` a cross-reference to the function "filter".
- The default is ``None``, which doesn't reassign the default role.
-
- The default role can always be set within individual documents using the
- standard reST :dir:`default-role` directive.
-
- .. versionadded:: 0.4
-
.. confval:: add_function_parentheses
A boolean that decides whether parentheses are appended to function and
Modified: doctools/trunk/sphinx/config.py
==============================================================================
--- doctools/trunk/sphinx/config.py (original)
+++ doctools/trunk/sphinx/config.py Sun Aug 10 19:10:31 2008
@@ -45,6 +45,7 @@
pygments_style = ('sphinx', False),
templates_path = ([], False),
template_bridge = (None, False),
+ keep_warnings = (False, True),
# HTML options
html_title = (lambda self: '%s v%s documentation' %
Modified: doctools/trunk/sphinx/environment.py
==============================================================================
--- doctools/trunk/sphinx/environment.py (original)
+++ doctools/trunk/sphinx/environment.py Sun Aug 10 19:10:31 2008
@@ -142,8 +142,7 @@
"""
Add our own transforms.
"""
- transforms = [DefaultSubstitutions, MoveModuleTargets,
- FilterMessages, HandleCodeBlocks]
+ transforms = [DefaultSubstitutions, MoveModuleTargets, HandleCodeBlocks]
def get_transforms(self):
tf = standalone.Reader.get_transforms(self)
return tf + self.transforms
@@ -491,6 +490,7 @@
doctree = publish_doctree(None, src_path, FileInput,
settings_overrides=self.settings,
reader=SphinxStandaloneReader())
+ self.filter_messages(doctree)
self.process_dependencies(docname, doctree)
self.process_images(docname, doctree)
self.process_metadata(docname, doctree)
@@ -532,6 +532,15 @@
else:
return doctree
+ def filter_messages(self, doctree):
+ """
+ Filter system messages from a doctree.
+ """
+ filterlevel = self.config.keep_warnings and 2 or 5
+ for node in doctree.traverse(nodes.system_message):
+ if node['level'] < filterlevel:
+ node.replace_self([])
+
def process_dependencies(self, docname, doctree):
"""
Process docutils-generated dependency info.
Modified: doctools/trunk/tests/root/conf.py
==============================================================================
--- doctools/trunk/tests/root/conf.py (original)
+++ doctools/trunk/tests/root/conf.py Sun Aug 10 19:10:31 2008
@@ -60,6 +60,8 @@
# for source files.
exclude_trees = ['_build']
+keep_warnings = True
+
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
More information about the Python-checkins
mailing list