Add new universal config value ``exclude_patterns``, with glob-style exclude patterns.

This makes the old ``unused_docs``, ``exclude_trees`` and ``exclude_dirnames`` obsolete.

2 files changed, 41 insertions, 0 deletions

diff --git a/doc/conf.py b/doc/conf.py
index ce87c54e..feda5fd1 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -18,6 +18,8 @@ source_suffix = '.rst'
 # The master toctree document.
 master_doc = 'contents'
 
+exclude_patterns = ['_build']
+
 # General substitutions.
 project = 'Sphinx'
 copyright = '2007-2010, Georg Brandl'
diff --git a/doc/config.rst b/doc/config.rst
index 60dc0499..be956ffa 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -87,12 +87,37 @@ General configuration
    The document name of the "master" document, that is, the document that
    contains the root :dir:`toctree` directive.  Default is ``'contents'``.
 
+.. confval:: exclude_patterns
+
+   A list of glob-style patterns that should be excluded when looking for source
+   files. [#]_ They are matched against the source file names relative to the
+   source directory, using slashes as directory separators on all platforms.
+
+   Example patterns:
+
+   - ``'library/xml.rst'`` -- ignores the ``library/xml.rst`` file (replaces
+     entry in :confval:`unused_docs`
+   - ``'library/xml'`` -- ignores the ``library/xml`` directory (replaces entry
+     in :confval:`exclude_trees`)
+   - ``'library/xml*'`` -- ignores all files and directories starting with
+     ``library/xml``
+   - ``'**/.svn'`` -- ignores all ``.svn`` directories (replaces entry in
+     :confval:`exclude_dirnames`)
+
+   :confval:`exclude_patterns` is also consulted when looking for static files
+   in :confval:`html_static_path`.
+
+   .. versionadded:: 1.0
+
 .. 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.
 
+   .. deprecated:: 1.0
+      Use :confval:`exclude_patterns` instead.
+
 .. confval:: exclude_trees
 
    A list of directory paths, relative to the source directory, that are to be
@@ -101,6 +126,9 @@ General configuration
 
    .. versionadded:: 0.4
 
+   .. deprecated:: 1.0
+      Use :confval:`exclude_patterns` instead.
+
 .. confval:: exclude_dirnames
 
    A list of directory names that are to be excluded from any recursive
@@ -110,6 +138,9 @@ General configuration
 
    .. versionadded:: 0.5
 
+   .. deprecated:: 1.0
+      Use :confval:`exclude_patterns` instead.
+
 .. confval:: locale_dirs
 
    .. versionadded:: 0.5
@@ -797,3 +828,11 @@ These options influence LaTeX output.
 
    .. deprecated:: 0.5
       Use the ``'pointsize'`` key in the :confval:`latex_elements` value.
+
+
+.. rubric:: Footnotes
+
+.. [#] A note on available globbing syntax: you can use the standard shell
+       constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that
+       these all don't match slashes.  A double star ``**`` can be used to match
+       any sequence of characters *including* slashes.