From 44f6adef98e207eb2587609bb89b7e06c5f16f41 Mon Sep 17 00:00:00 2001
From: Attila Fazekas <afazekas@redhat.com>
Date: Wed, 31 Jul 2013 09:06:28 +0200
Subject: Hierarchical sphinx API documentation generation

* Adding a new pbr boolean option 'autodoc_tree_index_modules' for
  creating a package/module hierarchy oriented API documentation.
* Using the sphinx.apidoc module in order to
  generate the *.rst files and the modules.rst.
  The sphinx.apidoc.main function call expected to be more future proof,
    than the other options.

Change-Id: I145086387edf6b042368d4c16dd64948f67606b0
---
 pbr/packaging.py | 35 ++++++++++++++++++++++++++---------
 1 file changed, 26 insertions(+), 9 deletions(-)

diff --git a/pbr/packaging.py b/pbr/packaging.py
index 526b5c3..f887adc 100644
--- a/pbr/packaging.py
+++ b/pbr/packaging.py
@@ -501,6 +501,7 @@ class LocalSDist(sdist.sdist):
         sdist.sdist.run(self)
 
 try:
+    from sphinx import apidoc
     from sphinx import application
     from sphinx import config
     from sphinx import setup_command
@@ -510,17 +511,21 @@ try:
         command_name = 'build_sphinx'
         builders = ['html', 'man']
 
-        def generate_autoindex(self):
+        def _get_source_dir(self):
             option_dict = self.distribution.get_option_dict('build_sphinx')
-            log.info("[pbr] Autodocumenting from %s"
-                     % os.path.abspath(os.curdir))
-            modules = {}
             if 'source_dir' in option_dict:
                 source_dir = os.path.join(option_dict['source_dir'][1], 'api')
             else:
                 source_dir = 'doc/source/api'
             if not os.path.exists(source_dir):
                 os.makedirs(source_dir)
+            return source_dir
+
+        def generate_autoindex(self):
+            log.info("[pbr] Autodocumenting from %s"
+                     % os.path.abspath(os.curdir))
+            modules = {}
+            source_dir = self._get_source_dir()
             for pkg in self.distribution.packages:
                 if '.' not in pkg:
                     for dirpath, dirnames, files in os.walk(pkg):
@@ -547,6 +552,10 @@ try:
                         output_file.write(_rst_template % values)
                     autoindex.write("   %s.rst\n" % module)
 
+        def _sphinx_tree(self):
+                source_dir = self._get_source_dir()
+                apidoc.main(['apidoc', '.', '-H', 'Modules', '-o', source_dir])
+
         def _sphinx_run(self):
             if not self.verbose:
                 status_stream = io.StringIO()
@@ -587,11 +596,19 @@ try:
 
         def run(self):
             option_dict = self.distribution.get_option_dict('pbr')
-            if ('autodoc_index_modules' in option_dict and
-                    option_dict.get(
-                        'autodoc_index_modules')[1].lower() in TRUE_VALUES and
-                    not os.getenv('SPHINX_DEBUG')):
-                self.generate_autoindex()
+            tree_index = get_boolean_option(option_dict,
+                                            'autodoc_tree_index_modules',
+                                            'AUTODOC_TREE_INDEX_MODULES')
+            auto_index = get_boolean_option(option_dict,
+                                            'autodoc_index_modules',
+                                            'AUTODOC_INDEX_MODULES')
+            if not os.getenv('SPHINX_DEBUG'):
+                #NOTE(afazekas): These options can be used together,
+                # but they do a very similar thing in a difffernet way
+                if tree_index:
+                    self._sphinx_tree()
+                if auto_index:
+                    self.generate_autoindex()
 
             for builder in self.builders:
                 self.builder = builder
-- 
cgit v1.2.1