New config value "keep_warnings", default is to discard the from the saved doctrees.

CHANGES

@@ -22,6 +22,10 @@ New features added
   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

doc/config.rst

@@ -74,6 +74,79 @@ General configuration
    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 @@ General configuration
    * ``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 @@ General configuration
    %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 @@ General configuration
       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

sphinx/config.py

@@ -45,6 +45,7 @@ class Config(object):
         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' %

sphinx/environment.py

@@ -142,8 +142,7 @@ class SphinxStandaloneReader(standalone.Reader):
     """
     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 @@ class BuildEnvironment:
         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 @@ class BuildEnvironment:
         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.

tests/root/conf.py

@@ -60,6 +60,8 @@ today_fmt = '%B %d, %Y'
 # for source files.
 exclude_trees = ['_build']
 
+keep_warnings = True
+
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True