Merge "Generate API documentation"

2 files changed, 74 insertions, 3 deletions

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 77162fa..1356966 100644
--- a/doc/source/conf.py
+++ b/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 ----------------------------------------------------
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index bbf845b..29c799e 100644
--- a/doc/source/index.rst
+++ b/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
@@ -16,10 +21,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