Add initial docs.

Change-Id: I1f8407597105a914945c932ff55945c8005e273c

.gitignore

@@ -13,3 +13,5 @@ python_glanceclient.egg-info
 ChangeLog
 run_tests.err.log
 .tox
+doc/source/api
+*.egg

doc/source/conf.py

@@ -0,0 +1,60 @@
+# -*- coding: utf-8 -*-
+#
+
+import sys, os
+
+project = 'python-glanceclient'
+
+# -- General configuration -----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']
+
+# autodoc generation is a bit aggressive and a nuisance when doing heavy
+# text edit cycles.
+# execute "export SPHINX_DEBUG=1" in your terminal to disable
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+copyright = u'OpenStack LLC'
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+html_theme = 'nature'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = '%sdoc' % project
+
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index',
+    '%s.tex' % project,
+    u'%s Documentation' % project,
+    u'OpenStack LLC', 'manual'),
+]
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'http://docs.python.org/': None}

doc/source/index.rst

@@ -0,0 +1,17 @@
+Python bindings to the OpenStack Images API
+===========================================
+
+This is a client for OpenStack Images API. Contents:
+
+.. toctree::
+   :maxdepth: 1
+
+   api/autoindex
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

glanceclient/openstack/common/setup.py

@@ -164,12 +164,27 @@ def generate_authors():
                 with open(old_authors, "r") as old_authors_fh:
                     new_authors_fh.write('\n' + old_authors_fh.read())
 
+_rst_template = """%(heading)s
+%(underline)s
+
+.. automodule:: %(module)s
+  :members:
+  :undoc-members:
+  :show-inheritance:
+"""
+
 
 def get_cmdclass():
     """Return dict of commands to run from setup.py."""
 
     cmdclass = dict()
 
+    def _find_modules(arg, dirname, files):
+        for filename in files:
+            if filename.endswith('.py') and filename != '__init__.py':
+                arg["%s.%s" % (dirname.replace('/', '.'),
+                               filename[:-3])] = True
+
     class LocalSDist(sdist.sdist):
         """Builds the ChangeLog and Authors files from VC first."""
 
@@ -188,10 +203,47 @@ def get_cmdclass():
         from sphinx.setup_command import BuildDoc
 
         class LocalBuildDoc(BuildDoc):
+            def generate_autoindex(self):
+                print "**Autodocumenting from %s" % os.path.abspath(os.curdir)
+                modules = {}
+                option_dict = self.distribution.get_option_dict('build_sphinx')
+                source_dir = os.path.join(option_dict['source_dir'][1], 'api')
+                if not os.path.exists(source_dir):
+                    os.makedirs(source_dir)
+                for pkg in self.distribution.packages:
+                    if '.' not in pkg:
+                        os.path.walk(pkg, _find_modules, modules)
+                module_list = modules.keys()
+                module_list.sort()
+                autoindex_filename = os.path.join(source_dir, 'autoindex.rst')
+                with open(autoindex_filename, 'w') as autoindex:
+                    autoindex.write(""".. toctree::
+   :maxdepth: 1
+
+""")
+                    for module in module_list:
+                        output_filename = os.path.join(source_dir,
+                                                       "%s.rst" % module)
+                        heading = "The :mod:`%s` Module" % module
+                        underline = "=" * len(heading)
+                        values = dict(module=module, heading=heading,
+                                      underline=underline)
+
+                        print "Generating %s" % output_filename
+                        with open(output_filename, 'w') as output_file:
+                            output_file.write(_rst_template % values)
+                        autoindex.write("   %s.rst\n" % module)
+
             def run(self):
+                if not os.getenv('SPHINX_DEBUG'):
+                    self.generate_autoindex()
+
                 for builder in ['html', 'man']:
                     self.builder = builder
                     self.finalize_options()
+                    self.project = self.distribution.get_name()
+                    self.version = self.distribution.get_version()
+                    self.release = self.distribution.get_version()
                     BuildDoc.run(self)
         cmdclass['build_sphinx'] = LocalBuildDoc
     except ImportError:

setup.py

@@ -3,17 +3,12 @@ import sys
 
 import setuptools
 
-from glanceclient.openstack.common.setup import generate_authors
-from glanceclient.openstack.common.setup import parse_requirements
-from glanceclient.openstack.common.setup import parse_dependency_links
-from glanceclient.openstack.common.setup import write_git_changelog
+from glanceclient.openstack.common import setup
 
 
-requires = parse_requirements()
-dependency_links = parse_dependency_links()
-tests_require = parse_requirements(['tools/test-requires'])
-write_git_changelog()
-generate_authors()
+requires = setup.parse_requirements()
+dependency_links = setup.parse_dependency_links()
+tests_require = setup.parse_requirements(['tools/test-requires'])
 
 if sys.version_info < (2, 6):
     requires.append('simplejson')
@@ -41,6 +36,7 @@ setuptools.setup(
         'Operating System :: OS Independent',
         'Programming Language :: Python',
     ],
+    cmdclass=setup.get_cmdclass(),
     install_requires=requires,
     dependency_links=dependency_links,
     tests_require=tests_require,