autodoc: allow to exclude modules from auto-generation

Some projects need to not generate and publish documentation for some of
their modules. This patch adds an option to list modules that should be
excluded from documentation auto generation.

Change-Id: I944a6ad5faa113ca26eb32b78be1bfc41e1387ef

2 files changed, 30 insertions, 7 deletions

diff --git a/pbr/packaging.py b/pbr/packaging.py
index 65a1f65..f5b138d 100644
--- a/pbr/packaging.py
+++ b/pbr/packaging.py
@@ -701,7 +701,7 @@ try:
                 os.makedirs(source_dir)
             return source_dir
 
-        def generate_autoindex(self):
+        def generate_autoindex(self, excluded_modules=None):
             log.info("[pbr] Autodocumenting from %s"
                      % os.path.abspath(os.curdir))
             modules = {}
@@ -710,8 +710,10 @@ try:
                 if '.' not in pkg:
                     for dirpath, dirnames, files in os.walk(pkg):
                         _find_modules(modules, dirpath, files)
-            module_list = list(modules.keys())
-            module_list.sort()
+            module_list = set(modules.keys())
+            if excluded_modules is not None:
+                module_list -= set(excluded_modules)
+            module_list = sorted(module_list)
             autoindex_filename = os.path.join(source_dir, 'autoindex.rst')
             with open(autoindex_filename, 'w') as autoindex:
                 autoindex.write(""".. toctree::
@@ -792,7 +794,10 @@ try:
                 if tree_index:
                     self._sphinx_tree()
                 if auto_index:
-                    self.generate_autoindex()
+                    self.generate_autoindex(
+                        option_dict.get(
+                            "autodoc_exclude_modules",
+                            [None, ""])[1].split())
 
             for builder in self.builders:
                 self.builder = builder
diff --git a/pbr/tests/test_setup.py b/pbr/tests/test_setup.py
index 8310e14..80d9a70 100644
--- a/pbr/tests/test_setup.py
+++ b/pbr/tests/test_setup.py
@@ -192,6 +192,10 @@ class BuildSphinxTest(base.BaseTestCase):
     scenarios = [
         ('true_autodoc_caps',
          dict(has_opt=True, autodoc='True', has_autodoc=True)),
+        ('true_autodoc_caps_with_excludes',
+         dict(has_opt=True, autodoc='True', has_autodoc=True,
+              excludes="fake_package.fake_private_module\n"
+              "fake_package.unknown_module")),
         ('true_autodoc_lower',
          dict(has_opt=True, autodoc='true', has_autodoc=True)),
         ('false_autodoc',
@@ -211,12 +215,19 @@ class BuildSphinxTest(base.BaseTestCase):
         self.distr.command_options["build_sphinx"] = {
             "source_dir": ["a", "."]}
         pkg_fixture = fixtures.PythonPackage(
-            "fake_package", [("fake_module.py", b"")])
+            "fake_package", [("fake_module.py", b""),
+                             ("fake_private_module.py", b"")])
         self.useFixture(pkg_fixture)
         self.useFixture(base.DiveDir(pkg_fixture.base))
+        self.distr.command_options["pbr"] = {}
+        if hasattr(self, "excludes"):
+            self.distr.command_options["pbr"]["autodoc_exclude_modules"] = (
+                'setup.cfg',
+                "fake_package.fake_private_module\n"
+                "fake_package.unknown_module")
         if self.has_opt:
-            self.distr.command_options["pbr"] = {
-                "autodoc_index_modules": ('setup.cfg', self.autodoc)}
+            options = self.distr.command_options["pbr"]
+            options["autodoc_index_modules"] = ('setup.cfg', self.autodoc)
 
     def test_build_doc(self):
         build_doc = packaging.LocalBuildDoc(self.distr)
@@ -227,6 +238,13 @@ class BuildSphinxTest(base.BaseTestCase):
         self.assertTrue(
             os.path.exists(
                 "api/fake_package.fake_module.rst") == self.has_autodoc)
+        if not self.has_autodoc or hasattr(self, "excludes"):
+            assertion = self.assertFalse
+        else:
+            assertion = self.assertTrue
+        assertion(
+            os.path.exists(
+                "api/fake_package.fake_private_module.rst"))
 
     def test_builders_config(self):
         build_doc = packaging.LocalBuildDoc(self.distr)