openstack/python-glanceclient
Code Issues Proposed changes

Generate API documentation

Browse Source 
As a new user I found navigating the documentation difficult.  The
flow was a bit unclear and searches bring up old versions of API
references that aren't included in the current documentation.

This
 - provides an introduction to the tools similar to other projects
 - generates API references for the v1 and v2 client
 - fixes some minor docstring issues
 - adds doc/* to pep8 tests to check the conf.py

The API generation code is cribbed from python-novaclient

Change-Id: I65772127679d7afd5e7e48ca7872366b01382f21
This commit is contained in:
Ian Wienand 2014-10-08 10:25:33 +11:00
parent a3eaafefbd
commit f272ab3ae4
5 changed files with 89 additions and 8 deletions

57
doc/source/conf.py

@ -1,3 +1,18 @@
# Copyright 2015 OpenStack Foundation
# 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.
# -*- coding: utf-8 -*-
#
@ -7,6 +22,48 @@ import sys
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__),
'..', '..')))
BASE_DIR = os.path.dirname(os.path.abspath(__file__))
ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", ".."))
def gen_ref(ver, title, names):
refdir = os.path.join(BASE_DIR, "ref")
pkg = "glanceclient"
if ver:
pkg = "%s.%s" % (pkg, ver)
refdir = os.path.join(refdir, ver)
if not os.path.exists(refdir):
os.makedirs(refdir)
idxpath = os.path.join(refdir, "index.rst")
with open(idxpath, "w") as idx:
idx.write(("%(title)s\n"
"%(signs)s\n"
"\n"
".. toctree::\n"
" :maxdepth: 1\n"
"\n") % {"title": title, "signs": "=" * len(title)})
for name in names:
idx.write(" %s\n" % name)
rstpath = os.path.join(refdir, "%s.rst" % name)
with open(rstpath, "w") as rst:
rst.write(("%(title)s\n"
"%(signs)s\n"
"\n"
".. automodule:: %(pkg)s.%(name)s\n"
" :members:\n"
" :undoc-members:\n"
" :show-inheritance:\n"
" :noindex:\n")
% {"title": name.capitalize(),
"signs": "=" * len(name),
"pkg": pkg, "name": name})
gen_ref(None, "API", ["client", "exc"])
gen_ref("v1", "OpenStack Images Version 1 Client Reference",
["client", "images", "image_members"])
gen_ref("v2", "OpenStack Images Version 2 Client Reference",
["client", "images", "image_tags",
"image_members", "tasks", "metadefs"])
# -- General configuration ----------------------------------------------------

20
doc/source/index.rst

@ -1,5 +1,10 @@
Python Bindings for the OpenStack Images API
============================================
This is a client for the OpenStack Images API. There's :doc:`a Python API <ref/index>` (the :mod:`glanceclient` module) and a :doc:`command-line script<man/glance>` (installed as :program:`glance`).
Python API
==========
----------
In order to use the python api directly, you must first obtain an auth token and identify which endpoint you wish to speak to. Once you have done so, you can use the API like so::
>>> from glanceclient import Client
@ -15,10 +20,19 @@ In order to use the python api directly, you must first obtain an auth token and
f.write(chunk)
>>> image.delete()
For an API v2 example see also :doc:`apiv2`.
Python API Reference
~~~~~~~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 2
ref/index
ref/v1/index
ref/v2/index
Command-line Tool
=================
-----------------
In order to use the CLI, you must provide your OpenStack username, password, tenant, and auth endpoint. Use the corresponding configuration options (``--os-username``, ``--os-password``, ``--os-tenant-id``, and ``--os-auth-url``) or set them in environment variables::
export OS_USERNAME=user

9
glanceclient/client.py

@ -19,6 +19,15 @@ from glanceclient.common import utils
def Client(version=None, endpoint=None, *args, **kwargs):
"""Client for the OpenStack Images API.
Generic client for the OpenStack Images API. See version classes
for specific details.
:param string version: The version of API to use. Note this is
deprecated and should be passed as part of the URL
(http://$HOST:$PORT/v$VERSION_NUMBER).
"""
if version is not None:
warnings.warn(("`version` keyword is being deprecated. Please pass the"
" version as part of the URL. "

9
glanceclient/v2/images.py

@ -38,10 +38,11 @@ class Controller(object):
return warlock.model_factory(schema.raw(), schemas.SchemaBasedModel)
def list(self, **kwargs):
"""Retrieve a listing of Image objects
"""Retrieve a listing of Image objects.
:param page_size: Number of images to request in each paginated request
:returns generator over list of Images
:param page_size: Number of images to request in each
paginated request.
:returns: generator over list of Images.
"""
ori_validate_fun = self.model.validate
@ -183,7 +184,7 @@ class Controller(object):
:param image_id: ID of the image to modify.
:param remove_props: List of property names to remove
:param **kwargs: Image attribute names and their new values.
:param \*\*kwargs: Image attribute names and their new values.
"""
image = self.get(image_id)
for (key, value) in kwargs.items():

2
tox.ini

@ -38,4 +38,4 @@ downloadcache = ~/cache/pip
# H404 multi line docstring should start with a summary
ignore = F403,F812,F821,H233,H302,H303,H404
show-source = True
exclude = .venv,.tox,dist,doc,*egg,build
exclude = .venv,.tox,dist,*egg,build