Add exclude_trees config value.

CHANGES

@@ -14,6 +14,9 @@ New features added
 * The new config value `html_use_index` can be used to switch index
   generation in HTML documents off.
 
+* The new `exclude_trees` config option can be used to exclude whole
+  subtrees from the search for source files.
+
 Bugs fixed
 ----------
 

doc/config.rst

@@ -117,6 +117,14 @@ General configuration
 
    .. 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
@@ -252,7 +260,7 @@ that use Sphinx' HTMLWriter class.
 
    If true, add an index to the HTML documents.  Default is ``True``.
 
-   .. versionadded:: 0.5
+   .. versionadded:: 0.4
 
 .. confval:: html_copy_source
 

sphinx/config.py

@@ -39,6 +39,7 @@ class Config(object):
         source_suffix = ('.rst', True),
         unused_docs = ([], True),
         exclude_dirs = ([], True),
+        exclude_trees = ([], True),
         add_function_parentheses = (True, True),
         add_module_names = (True, True),
         show_authors = (False, True),

sphinx/environment.py

@@ -325,10 +325,12 @@ class BuildEnvironment:
         """
         Find all source files in the source dir and put them in self.found_docs.
         """
-        exclude_dirs = [d.replace(SEP, path.sep) for d in config.exclude_dirs]
+        exclude_dirs  = [d.replace(SEP, path.sep) for d in config.exclude_dirs]
+        exclude_trees = [d.replace(SEP, path.sep) for d in config.exclude_trees]
         self.found_docs = set(get_matching_docs(
             self.srcdir, config.source_suffix, exclude_docs=set(config.unused_docs),
-            exclude_dirs=exclude_dirs, prune_dirs=['_sources']))
+            exclude_dirs=exclude_dirs, exclude_trees=exclude_trees,
+            exclude_dirnames=['_sources']))
 
     def get_outdated_files(self, config_changed):
         """

sphinx/util/__init__.py

@@ -75,12 +75,14 @@ def walk(top, topdown=True, followlinks=False):
         yield top, dirs, nondirs
 
 
-def get_matching_docs(dirname, suffix, exclude_docs=(), exclude_dirs=(), prune_dirs=()):
+def get_matching_docs(dirname, suffix, exclude_docs=(), exclude_dirs=(),
+                      exclude_trees=(), exclude_dirnames=()):
     """
     Get all file names (without suffix) matching a suffix in a
     directory, recursively.
 
-    Exclude files in *exclude*, prune directories in *prune*.
+    Exclude docs in *exclude_docs*, exclude dirs in *exclude_dirs*,
+    prune dirs in *exclude_trees*, prune dirnames in *exclude_dirnames*.
     """
     pattern = '*' + suffix
     # dirname is a normalized absolute path.
@@ -89,9 +91,12 @@ def get_matching_docs(dirname, suffix, exclude_docs=(), exclude_dirs=(), prune_d
     for root, dirs, files in walk(dirname, followlinks=True):
         if root[dirlen:] in exclude_dirs:
             continue
+        if root[dirlen:] in exclude_trees:
+            del dirs[:]
+            continue
         dirs.sort()
         files.sort()
-        for prunedir in prune_dirs:
+        for prunedir in exclude_dirnames:
             if prunedir in dirs:
                 dirs.remove(prunedir)
         for sfile in files: