From b3f1de1bf7d7d155a3d4234fb09f4480ec11ffbb Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 10 Aug 2008 17:10:31 +0000 Subject: [PATCH] New config value "keep_warnings", default is to discard the from the saved doctrees. --- CHANGES | 4 ++ doc/config.rst | 131 +++++++++++++++++++++++------------------- sphinx/config.py | 1 + sphinx/environment.py | 13 ++++- tests/root/conf.py | 2 + 5 files changed, 91 insertions(+), 60 deletions(-) diff --git a/CHANGES b/CHANGES index ac43e954c..33cb1f990 100644 --- a/CHANGES +++ b/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 diff --git a/doc/config.rst b/doc/config.rst index 424e46cf4..33f7decbc 100644 --- a/doc/config.rst +++ b/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 diff --git a/sphinx/config.py b/sphinx/config.py index 5139f8a3b..f28bb0d39 100644 --- a/sphinx/config.py +++ b/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' % diff --git a/sphinx/environment.py b/sphinx/environment.py index 115997552..b1bbe549b 100644 --- a/sphinx/environment.py +++ b/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. diff --git a/tests/root/conf.py b/tests/root/conf.py index 5d449b109..ae4e2fa81 100644 --- a/tests/root/conf.py +++ b/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