Add initial docs.

Change-Id: I846eec12e800c15a545946604fe77a0a6b83fb46

.gitignore

@@ -10,3 +10,6 @@ run_tests.err.log
 run_tests.log
 .venv/
 .tox/
+.autogenerated
+doc/build/
+doc/source/api/

doc/source/conf.py

@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+#
+
+import sys
+import os
+
+project = 'python-quantumclient'
+
+# -- 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']
+
+# 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 Network API
+============================================
+
+This is a client for OpenStack Network API. Contents:
+
+.. toctree::
+   :maxdepth: 1
+
+   api/autoindex
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

openstack-common.conf

@@ -0,0 +1,7 @@
+[DEFAULT]
+
+# The list of modules to copy from openstack-common
+modules=setup
+
+# The base module to hold the copy of openstack.common
+base=quantumclient

quantumclient/openstack/common/setup.py

@@ -0,0 +1,252 @@
+# vim: tabstop=4 shiftwidth=4 softtabstop=4
+
+# Copyright 2011 OpenStack LLC.
+# All Rights Reserved.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+"""
+Utilities with minimum-depends for use in setup.py
+"""
+
+import os
+import re
+import subprocess
+
+from setuptools.command import sdist
+
+
+def parse_mailmap(mailmap='.mailmap'):
+    mapping = {}
+    if os.path.exists(mailmap):
+        fp = open(mailmap, 'r')
+        for l in fp:
+            l = l.strip()
+            if not l.startswith('#') and ' ' in l:
+                canonical_email, alias = [x for x in l.split(' ')
+                                          if x.startswith('<')]
+                mapping[alias] = canonical_email
+    return mapping
+
+
+def canonicalize_emails(changelog, mapping):
+    """Takes in a string and an email alias mapping and replaces all
+       instances of the aliases in the string with their real email.
+    """
+    for alias, email in mapping.iteritems():
+        changelog = changelog.replace(alias, email)
+    return changelog
+
+
+# Get requirements from the first file that exists
+def get_reqs_from_files(requirements_files):
+    reqs_in = []
+    for requirements_file in requirements_files:
+        if os.path.exists(requirements_file):
+            return open(requirements_file, 'r').read().split('\n')
+    return []
+
+
+def parse_requirements(requirements_files=['requirements.txt',
+                                           'tools/pip-requires']):
+    requirements = []
+    for line in get_reqs_from_files(requirements_files):
+        # For the requirements list, we need to inject only the portion
+        # after egg= so that distutils knows the package it's looking for
+        # such as:
+        # -e git://github.com/openstack/nova/master#egg=nova
+        if re.match(r'\s*-e\s+', line):
+            requirements.append(re.sub(r'\s*-e\s+.*#egg=(.*)$', r'\1',
+                                line))
+        # such as:
+        # http://github.com/openstack/nova/zipball/master#egg=nova
+        elif re.match(r'\s*https?:', line):
+            requirements.append(re.sub(r'\s*https?:.*#egg=(.*)$', r'\1',
+                                line))
+        # -f lines are for index locations, and don't get used here
+        elif re.match(r'\s*-f\s+', line):
+            pass
+        else:
+            requirements.append(line)
+
+    return requirements
+
+
+def parse_dependency_links(requirements_files=['requirements.txt',
+                                               'tools/pip-requires']):
+    dependency_links = []
+    # dependency_links inject alternate locations to find packages listed
+    # in requirements
+    for line in get_reqs_from_files(requirements_files):
+        # skip comments and blank lines
+        if re.match(r'(\s*#)|(\s*$)', line):
+            continue
+        # lines with -e or -f need the whole line, minus the flag
+        if re.match(r'\s*-[ef]\s+', line):
+            dependency_links.append(re.sub(r'\s*-[ef]\s+', '', line))
+        # lines that are only urls can go in unmolested
+        elif re.match(r'\s*https?:', line):
+            dependency_links.append(line)
+    return dependency_links
+
+
+def write_requirements():
+    venv = os.environ.get('VIRTUAL_ENV', None)
+    if venv is not None:
+        with open("requirements.txt", "w") as req_file:
+            output = subprocess.Popen(["pip", "-E", venv, "freeze", "-l"],
+                                      stdout=subprocess.PIPE)
+            requirements = output.communicate()[0].strip()
+            req_file.write(requirements)
+
+
+def _run_shell_command(cmd):
+    output = subprocess.Popen(["/bin/sh", "-c", cmd],
+                              stdout=subprocess.PIPE)
+    return output.communicate()[0].strip()
+
+
+def write_vcsversion(location):
+    """Produce a vcsversion dict that mimics the old one produced by bzr.
+    """
+    if os.path.isdir('.git'):
+        branch_nick_cmd = 'git branch | grep -Ei "\* (.*)" | cut -f2 -d" "'
+        branch_nick = _run_shell_command(branch_nick_cmd)
+        revid_cmd = "git rev-parse HEAD"
+        revid = _run_shell_command(revid_cmd).split()[0]
+        revno_cmd = "git log --oneline | wc -l"
+        revno = _run_shell_command(revno_cmd)
+        with open(location, 'w') as version_file:
+            version_file.write("""
+# This file is automatically generated by setup.py, So don't edit it. :)
+version_info = {
+    'branch_nick': '%s',
+    'revision_id': '%s',
+    'revno': %s
+}
+""" % (branch_nick, revid, revno))
+
+
+def write_git_changelog():
+    """Write a changelog based on the git changelog."""
+    if os.path.isdir('.git'):
+        git_log_cmd = 'git log --stat'
+        changelog = _run_shell_command(git_log_cmd)
+        mailmap = parse_mailmap()
+        with open("ChangeLog", "w") as changelog_file:
+            changelog_file.write(canonicalize_emails(changelog, mailmap))
+
+
+def generate_authors():
+    """Create AUTHORS file using git commits."""
+    jenkins_email = 'jenkins@review.openstack.org'
+    old_authors = 'AUTHORS.in'
+    new_authors = 'AUTHORS'
+    if os.path.isdir('.git'):
+        # don't include jenkins email address in AUTHORS file
+        git_log_cmd = ("git log --format='%aN <%aE>' | sort -u | "
+                       "grep -v " + jenkins_email)
+        changelog = _run_shell_command(git_log_cmd)
+        mailmap = parse_mailmap()
+        with open(new_authors, 'w') as new_authors_fh:
+            new_authors_fh.write(canonicalize_emails(changelog, mailmap))
+            if os.path.exists(old_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."""
+
+        def run(self):
+            write_git_changelog()
+            generate_authors()
+            # sdist.sdist is an old style class, can't use super()
+            sdist.sdist.run(self)
+
+    cmdclass['sdist'] = LocalSDist
+
+    # If Sphinx is installed on the box running setup.py,
+    # enable setup.py to build the documentation, otherwise,
+    # just ignore it
+    try:
+        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:
+        pass
+
+    return cmdclass

setup.cfg

@@ -1,3 +1,8 @@
+[build_sphinx]
+all_files = 1
+build-dir = doc/build
+source-dir = doc/source
+
 [nosetests]
 # NOTE(jkoelker) To run the test suite under nose install the following
 #                coverage http://pypi.python.org/pypi/coverage

setup.py

@@ -15,12 +15,11 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
-try:
+import os
-    from setuptools import setup, find_packages
+import sys
-except ImportError:
+import setuptools
-    from ez_setup import use_setuptools
+
-    use_setuptools()
+from quantumclient.openstack.common import setup
-    from setuptools import setup, find_packages
 
 import version
 
@@ -35,8 +34,8 @@ Summary = 'Client functionalities for Quantum'
 ShortDescription = Summary
 Description = Summary
 
-requires = [
+dependency_links = setup.parse_dependency_links()
-]
+tests_require = setup.parse_requirements(['tools/test-requires'])
 
 EagerResources = [
 ]
@@ -48,7 +47,7 @@ PackageData = {
 }
 
 
-setup(
+setuptools.setup(
     name=Name,
     version=Version,
     url=Url,
@@ -58,9 +57,11 @@ setup(
     long_description=Description,
     license=License,
     scripts=ProjectScripts,
-    install_requires=requires,
+    dependency_links=dependency_links,
+    tests_require=tests_require,
+    cmdclass=setup.get_cmdclass(),
     include_package_data=False,
-    packages=["quantumclient", "quantumclient.common"],
+    packages=setuptools.find_packages(exclude=['tests', 'tests.*']),
     package_data=PackageData,
     eager_resources=EagerResources,
     entry_points={

tools/test-requires

@@ -8,4 +8,4 @@ openstack.nose_plugin
 pep8==0.6.1
 sphinx>=1.1.2
 
--e git+https://review.openstack.org/p/openstack/quantum#egg=quantum-dev
+https://github.com/openstack/quantum/zipball/master#egg=quantum

tox.ini

@@ -2,56 +2,24 @@
 envlist = py26,py27,pep8
 
 [testenv]
-setenv =
+setenv = VIRTUAL_ENV={envdir}
-  VIRTUAL_ENV={envdir}
          NOSE_WITH_OPENSTACK=1
          NOSE_OPENSTACK_COLOR=1
          NOSE_OPENSTACK_RED=0.05
          NOSE_OPENSTACK_YELLOW=0.025
          NOSE_OPENSTACK_SHOW_ELAPSED=1
-deps =
+         NOSE_OPENSTACK_STDOUT=1
-  -r{toxinidir}/tools/test-requires
+deps = -r{toxinidir}/tools/test-requires
-commands = nosetests
+commands = nosetests {posargs}
-
-[testenv:pep8]
-commands =
-  pep8 --exclude=vcsversion.py,*.pyc --repeat --show-source quantumclient \
-    setup.py version.py
-
-[testenv:venv]
-commands = {posargs}
-
-[testenv:cover]
-commands =
-  nosetests --with-coverage --cover-html --cover-erase \
-    --cover-package=quantumclient
 
 [tox:jenkins]
 downloadcache = ~/cache/pip
 
-[testenv:jenkins26]
+[testenv:pep8]
-basepython = python2.6
+commands = pep8 --repeat --show-source --exclude=.venv,.tox,dist,doc .
-setenv = NOSE_WITH_XUNIT=1
-deps = file://{toxinidir}/.cache.bundle
 
-[testenv:jenkins27]
+[testenv:cover]
-basepython = python2.7
+setenv = NOSE_WITH_COVERAGE=1
-setenv = NOSE_WITH_XUNIT=1
-deps = file://{toxinidir}/.cache.bundle
 
-[testenv:jenkinspep8]
+[testenv:venv]
-deps = file://{toxinidir}/.cache.bundle
-commands =
-  pep8 --exclude=vcsversion.py,*.pyc --repeat --show-source quantumclient \
-    setup.py version.py
-
-[testenv:jenkinscover]
-deps = file://{toxinidir}/.cache.bundle
-setenv = NOSE_WITH_XUNIT=1
-commands =
-  nosetests --cover-erase --cover-package=quantumclient --with-xcoverage
-
-[testenv:jenkinsvenv]
-deps = file://{toxinidir}/.cache.bundle
-setenv = NOSE_WITH_XUNIT=1
 commands = {posargs}