From f7086ed40a9cf7b978a906179fd9d883c00e5eff Mon Sep 17 00:00:00 2001 From: Monty Taylor Date: Wed, 13 Jun 2012 16:10:57 -0400 Subject: [PATCH] Add initial docs. Change-Id: I846eec12e800c15a545946604fe77a0a6b83fb46 --- .gitignore | 3 + doc/source/conf.py | 58 +++++ doc/source/index.rst | 17 ++ openstack-common.conf | 7 + quantumclient/openstack/__init__.py | 0 quantumclient/openstack/common/__init__.py | 0 quantumclient/openstack/common/setup.py | 252 +++++++++++++++++++++ setup.cfg | 5 + setup.py | 23 +- tools/test-requires | 2 +- tox.ini | 60 ++--- 11 files changed, 369 insertions(+), 58 deletions(-) create mode 100644 doc/source/conf.py create mode 100644 doc/source/index.rst create mode 100644 openstack-common.conf create mode 100644 quantumclient/openstack/__init__.py create mode 100644 quantumclient/openstack/common/__init__.py create mode 100644 quantumclient/openstack/common/setup.py diff --git a/.gitignore b/.gitignore index 2fc28f418..14c363976 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,6 @@ run_tests.err.log run_tests.log .venv/ .tox/ +.autogenerated +doc/build/ +doc/source/api/ diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 000000000..fba29db68 --- /dev/null +++ b/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} diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 000000000..8032d6914 --- /dev/null +++ b/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` + diff --git a/openstack-common.conf b/openstack-common.conf new file mode 100644 index 000000000..35d48d06e --- /dev/null +++ b/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 diff --git a/quantumclient/openstack/__init__.py b/quantumclient/openstack/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/quantumclient/openstack/common/__init__.py b/quantumclient/openstack/common/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/quantumclient/openstack/common/setup.py b/quantumclient/openstack/common/setup.py new file mode 100644 index 000000000..429ba35c5 --- /dev/null +++ b/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 diff --git a/setup.cfg b/setup.cfg index 48000a777..394b128fe 100644 --- a/setup.cfg +++ b/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 diff --git a/setup.py b/setup.py index 087e1546b..e57b15eba 100644 --- a/setup.py +++ b/setup.py @@ -15,12 +15,11 @@ # License for the specific language governing permissions and limitations # under the License. -try: - from setuptools import setup, find_packages -except ImportError: - from ez_setup import use_setuptools - use_setuptools() - from setuptools import setup, find_packages +import os +import sys +import setuptools + +from quantumclient.openstack.common import setup 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={ diff --git a/tools/test-requires b/tools/test-requires index a048ab095..427a1b233 100644 --- a/tools/test-requires +++ b/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 diff --git a/tox.ini b/tox.ini index a5feeffaa..fce1185cf 100644 --- a/tox.ini +++ b/tox.ini @@ -2,56 +2,24 @@ envlist = py26,py27,pep8 [testenv] -setenv = - 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 = - -r{toxinidir}/tools/test-requires -commands = nosetests - -[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 +setenv = 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 + NOSE_OPENSTACK_STDOUT=1 +deps = -r{toxinidir}/tools/test-requires +commands = nosetests {posargs} [tox:jenkins] downloadcache = ~/cache/pip -[testenv:jenkins26] -basepython = python2.6 -setenv = NOSE_WITH_XUNIT=1 -deps = file://{toxinidir}/.cache.bundle +[testenv:pep8] +commands = pep8 --repeat --show-source --exclude=.venv,.tox,dist,doc . -[testenv:jenkins27] -basepython = python2.7 -setenv = NOSE_WITH_XUNIT=1 -deps = file://{toxinidir}/.cache.bundle +[testenv:cover] +setenv = NOSE_WITH_COVERAGE=1 -[testenv:jenkinspep8] -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 +[testenv:venv] commands = {posargs}