diff --git a/.gitignore b/.gitignore index 58c9e7e5..678f6396 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,5 @@ python_glanceclient.egg-info ChangeLog run_tests.err.log .tox +doc/source/api +*.egg diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 00000000..2e295e75 --- /dev/null +++ b/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} diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 00000000..b06aa4e9 --- /dev/null +++ b/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` + diff --git a/glanceclient/openstack/common/setup.py b/glanceclient/openstack/common/setup.py index 79b5a62b..429ba35c 100644 --- a/glanceclient/openstack/common/setup.py +++ b/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: diff --git a/setup.py b/setup.py index 750f9acf..935fc63a 100644 --- a/setup.py +++ b/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,