From 3582d6f1be6ee652abdc6ee7e8896fade240ffb1 Mon Sep 17 00:00:00 2001 From: JUN JIE NAN Date: Wed, 18 Dec 2013 16:04:58 +0800 Subject: [PATCH] Generate interfaces reference doc Add gen_ref in conf.py to generate reference doc to avoid maintaining these boilerplates. Change-Id: I6683c41d39685dcb7f7a619a36210a987c9e9825 --- doc/.gitignore | 1 + doc/source/api.rst | 1 + doc/source/conf.py | 42 +++++++++++++++++++++++++++ doc/source/index.rst | 1 + doc/source/ref/exceptions.rst | 8 ------ doc/source/ref/flavors.rst | 35 ----------------------- doc/source/ref/images.rst | 54 ----------------------------------- doc/source/ref/index.rst | 10 ------- doc/source/ref/servers.rst | 13 --------- 9 files changed, 45 insertions(+), 120 deletions(-) delete mode 100644 doc/source/ref/exceptions.rst delete mode 100644 doc/source/ref/flavors.rst delete mode 100644 doc/source/ref/images.rst delete mode 100644 doc/source/ref/index.rst delete mode 100644 doc/source/ref/servers.rst diff --git a/doc/.gitignore b/doc/.gitignore index 567609b12..8e0be80f5 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1 +1,2 @@ build/ +source/ref/ diff --git a/doc/source/api.rst b/doc/source/api.rst index 78c0a5c32..4ba9631c9 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -43,3 +43,4 @@ For more information, see the reference: :maxdepth: 2 ref/index + ref/v1_1/index diff --git a/doc/source/conf.py b/doc/source/conf.py index ee0b6837f..a4f48bd02 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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 diff --git a/doc/source/index.rst b/doc/source/index.rst index 00d1a81ea..c99841988 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -25,6 +25,7 @@ Contents: shell api ref/index + ref/v1_1/index releases Contributing diff --git a/doc/source/ref/exceptions.rst b/doc/source/ref/exceptions.rst deleted file mode 100644 index 5f593c73e..000000000 --- a/doc/source/ref/exceptions.rst +++ /dev/null @@ -1,8 +0,0 @@ -Exceptions -========== - -.. automodule:: novaclient.exceptions - :members: - :undoc-members: - :show-inheritance: - :noindex: diff --git a/doc/source/ref/flavors.rst b/doc/source/ref/flavors.rst deleted file mode 100644 index 1e04fe752..000000000 --- a/doc/source/ref/flavors.rst +++ /dev/null @@ -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 diff --git a/doc/source/ref/images.rst b/doc/source/ref/images.rst deleted file mode 100644 index 6f58c0ae1..000000000 --- a/doc/source/ref/images.rst +++ /dev/null @@ -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. diff --git a/doc/source/ref/index.rst b/doc/source/ref/index.rst deleted file mode 100644 index 2db23af4c..000000000 --- a/doc/source/ref/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -Version 1.1, Version 2 API Reference -======================================= - -.. toctree:: - :maxdepth: 1 - - exceptions - flavors - images - servers diff --git a/doc/source/ref/servers.rst b/doc/source/ref/servers.rst deleted file mode 100644 index 3a8e723d1..000000000 --- a/doc/source/ref/servers.rst +++ /dev/null @@ -1,13 +0,0 @@ -Servers -======= - -A virtual machine instance. - -Classes -------- - -.. automodule:: novaclient.v1_1.servers - :members: - :undoc-members: - :show-inheritance: - :noindex: