From 4acdad63ac54a3a2fac2fa9530a3d9c6d521f2c5 Mon Sep 17 00:00:00 2001
From: Edmond Kotowski <ekotowski@gmail.com>
Date: Wed, 11 Feb 2015 18:29:18 -0800
Subject: [PATCH] TroveClient API Documentation cleanup

- The documentation index page will now contain a
Version 1 API Reference section with links to each v1 module and
documentation for each method in that module.

- Copied python-novaclients gen_ref method into the doc/source/conf.py file
that dyanamically generates the sphinx .rst files for each trove v1 module.
When it runs it will create generate a new folder named ref/v1/ and will
contain each module such as instances.rst with the filled out automodule
sphinx code.

Ex: /ref/v1/instances.rst

.. automodule:: troveclient.v1.instances
    :members:
    :undoc-members:
    :show-inheritance:

Change-Id: Ib311486564f5b6def205590a1ccc2e493f3fef97
---
 doc/source/conf.py    | 48 +++++++++++++++++++++++++++++++++++++++++++
 doc/source/index.rst  |  3 +--
 doc/source/pydocs.rst | 16 ---------------
 3 files changed, 49 insertions(+), 18 deletions(-)
 delete mode 100644 doc/source/pydocs.rst

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 6c9148ef..c342ce9c 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -18,6 +18,54 @@
 #
 # -*- coding: utf-8 -*-
 
+import sys
+import os
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+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 = "troveclient"
+    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("v1", "Version 1 API Reference",
+        ["accounts", "backups", "client", "clusters", "configurations",
+         "databases", "datastores", "diagnostics", "flavors",
+         "hosts", "instances", "limits", "management", "metadata",
+         "quota", "root", "security_groups", "shell", "storage", "users"])
+
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 17242399..038e4066 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -19,11 +19,10 @@
    :maxdepth: 2
 
    usage
-   pydocs
+   ref/v1/index
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
diff --git a/doc/source/pydocs.rst b/doc/source/pydocs.rst
deleted file mode 100644
index a18b3388..00000000
--- a/doc/source/pydocs.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-PyDocs
-=================
-
-troveclient
---------------
-
-
-.. automodule:: troveclient
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-.. autoclass:: troveclient.compat.client.Dbaas
-    :members:
-    :undoc-members:
-    :show-inheritance: