Generate interfaces reference doc

Add gen_ref in conf.py to generate reference doc to avoid maintaining
these boilerplates.

Change-Id: I6683c41d39685dcb7f7a619a36210a987c9e9825
This commit is contained in:
JUN JIE NAN 2013-12-18 16:04:58 +08:00
parent 49be47367f
commit 3582d6f1be
9 changed files with 45 additions and 120 deletions

1
doc/.gitignore vendored
View File

@ -1 +1,2 @@
build/
source/ref/

View File

@ -43,3 +43,4 @@ For more information, see the reference:
:maxdepth: 2
ref/index
ref/v1_1/index

View File

@ -26,6 +26,48 @@ ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", ".."))
sys.path.insert(0, ROOT)
sys.path.insert(0, BASE_DIR)
def gen_ref(ver, title, names):
refdir = os.path.join(BASE_DIR, "ref")
pkg = "novaclient"
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, "Exceptions", ["exceptions"])
gen_ref("v1_1", "Version 1.1, Version 2 API Reference",
["flavors", "images", "servers", "hosts", "agents", "aggregates",
"availability_zones", "certs", "fixed_ips", "floating_ip_pools",
"floating_ips", "hypervisors", "keypairs", "limits", "networks",
"quota_classes", "quotas", "security_group_rules",
"security_groups", "services", "virtual_interfaces",
"volume_snapshots", "volumes", "volume_types"])
# -- General configuration ----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be

View File

@ -25,6 +25,7 @@ Contents:
shell
api
ref/index
ref/v1_1/index
releases
Contributing

View File

@ -1,8 +0,0 @@
Exceptions
==========
.. automodule:: novaclient.exceptions
:members:
:undoc-members:
:show-inheritance:
:noindex:

View File

@ -1,35 +0,0 @@
Flavors
=======
From Rackspace's API documentation:
A flavor is an available hardware configuration for a server. Each flavor
has a unique combination of disk space, memory capacity and priority for
CPU time.
Classes
-------
.. currentmodule:: novaclient.v1_1.flavors
.. autoclass:: FlavorManager
:members: get, list, find, findall
.. autoclass:: Flavor
:members:
.. attribute:: id
This flavor's ID.
.. attribute:: name
A human-readable name for this flavor.
.. attribute:: ram
The amount of RAM this flavor has, in MB.
.. attribute:: disk
The amount of disk space this flavor has, in MB

View File

@ -1,54 +0,0 @@
Images
======
.. currentmodule:: novaclient.v1_1.images
An "image" is a snapshot from which you can create new server instances.
From Rackspace's own API documentation:
An image is a collection of files used to create or rebuild a server.
Rackspace provides a number of pre-built OS images by default. You may
also create custom images from cloud servers you have launched. These
custom images are useful for backup purposes or for producing "gold"
server images if you plan to deploy a particular server configuration
frequently.
Classes
-------
.. autoclass:: ImageManager
:members: get, list, find, findall, delete
.. autoclass:: Image
:members: delete
.. attribute:: id
This image's ID.
.. attribute:: name
This image's name.
.. attribute:: created
The date/time this image was created.
.. attribute:: updated
The date/time this instance was updated.
.. attribute:: status
The status of this image (usually ``"SAVING"`` or ``ACTIVE``).
.. attribute:: progress
During saving of an image this'll be set to something between
0 and 100, representing a rough percentage done.
.. attribute:: serverId
If this image was created from a :class:`Server` then this attribute
will be set to the ID of the server whence this image came.

View File

@ -1,10 +0,0 @@
Version 1.1, Version 2 API Reference
=======================================
.. toctree::
:maxdepth: 1
exceptions
flavors
images
servers

View File

@ -1,13 +0,0 @@
Servers
=======
A virtual machine instance.
Classes
-------
.. automodule:: novaclient.v1_1.servers
:members:
:undoc-members:
:show-inheritance:
:noindex: