From 865a78a88623c83de46d977e9f1535e01ff7da0a Mon Sep 17 00:00:00 2001
From: Danny Hermes <daniel.j.hermes@gmail.com>
Date: Fri, 31 Jul 2015 13:01:44 -0700
Subject: [PATCH] Using caption with different toc sections instead of JS/CSS
 hack.

This fits within the Sphinx construct and would allow our docs to
be built on readthedocs.org.
---
 docs/_static/css/main.css   | 12 ++++++++++++
 docs/_static/js/main.js     | 10 ----------
 docs/_templates/layout.html |  1 -
 docs/conf.py                | 19 ++++++++++++++-----
 docs/index.rst              | 25 +++++++++++++++++++++++++
 tox.ini                     |  2 +-
 6 files changed, 52 insertions(+), 17 deletions(-)

diff --git a/docs/_static/css/main.css b/docs/_static/css/main.css
index 674948469063..eb7139223244 100755
--- a/docs/_static/css/main.css
+++ b/docs/_static/css/main.css
@@ -862,6 +862,18 @@ h2 .headerlink:hover {
     margin-top: 2em;
 }
 
+.side-nav > ul > li.toctree-l1 {
+    padding-left: 2em;
+}
+
+p.caption {
+    padding-left: 2em;
+}
+
+span.caption-text {
+    font-weight: bold;
+}
+
 .external-links img {
     margin-right: 0.3em;
     opacity: 0.3;
diff --git a/docs/_static/js/main.js b/docs/_static/js/main.js
index 35a57b701d32..dcd61f346e86 100755
--- a/docs/_static/js/main.js
+++ b/docs/_static/js/main.js
@@ -13,16 +13,6 @@ $('.headerlink').parent().each(function() {
   );
 });
 
-$('.side-nav').children('ul:nth-child(2)').children().each(function() {
-  var itemName = $(this).text();
-    if (itemName !== 'Datastore' &&
-        itemName !== 'Storage' &&
-        itemName !== 'Pub/Sub' &&
-        itemName !== 'BigQuery') {
-      $(this).css('padding-left','2em');
-  }
-});
-
 var apiQsSection;
 // don't even ask me why
 if ($('#cloud-datastore-in-10-seconds').length)
diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
index f3fe1e7f6279..ef28000ba8c9 100644
--- a/docs/_templates/layout.html
+++ b/docs/_templates/layout.html
@@ -127,7 +127,6 @@ <h1 class="page-title">Python</h1>
         {% block body %} {% endblock %}
       </section><!-- end of .content -->
       <nav class="side-nav">
-        <ul><li><a href="{{ pathto('index') }}">gcloud</a></li></ul>
         {{ toctree(includehidden=True, maxdepth=1, titles_only=True) }}
         <ul class="external-links">
           <li>
diff --git a/docs/conf.py b/docs/conf.py
index f4bca7d6cfdd..f4f0918e6cc5 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -17,6 +17,12 @@
 import sys
 import urllib
 
+import sphinx_rtd_theme
+
+
+ON_READ_THE_DOCS = os.environ.get('READTHEDOCS', None) == 'True'
+LOCAL_READ_THE_DOCS = os.environ.get('LOCAL_RTD', None) == 'True'
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -38,7 +44,10 @@
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+if ON_READ_THE_DOCS or LOCAL_READ_THE_DOCS:
+  templates_path = []
+else:
+  templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
@@ -103,10 +112,10 @@
 
 html_theme = 'classic'
 
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
-if on_rtd:
-  html_style = 'default.css'
-else:
+if LOCAL_READ_THE_DOCS:
+  html_theme = 'sphinx_rtd_theme'
+  html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+elif not ON_READ_THE_DOCS:
   html_style = 'css/main.css'
 
 # Theme options are theme-specific and customize the look and feel of a theme
diff --git a/docs/index.rst b/docs/index.rst
index 00de6de84f02..de647426ab81 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,8 +1,15 @@
 .. toctree::
   :maxdepth: 0
   :hidden:
+  :caption: gcloud
 
   gcloud-api
+
+.. toctree::
+  :maxdepth: 0
+  :hidden:
+  :caption: Datastore
+
   datastore-overview
   datastore-client
   datastore-entities
@@ -10,14 +17,32 @@
   datastore-queries
   datastore-transactions
   datastore-batches
+
+.. toctree::
+  :maxdepth: 0
+  :hidden:
+  :caption: Storage
+
   storage-api
   storage-blobs
   storage-buckets
   storage-acl
+
+.. toctree::
+  :maxdepth: 0
+  :hidden:
+  :caption: Pub/Sub
+
   pubsub-api
   pubsub-usage
   pubsub-topic
   pubsub-subscription
+
+.. toctree::
+  :maxdepth: 0
+  :hidden:
+  :caption: BigQuery
+
   bigquery-usage
 
 
diff --git a/tox.ini b/tox.ini
index 71f2591e054c..5ce81b771751 100644
--- a/tox.ini
+++ b/tox.ini
@@ -40,7 +40,7 @@ commands =
     sphinx-build -W -b html -d docs/_build/doctrees docs docs/_build/html
 deps =
     Sphinx
-passenv = {[testenv:system-tests]passenv} SPHINX_RELEASE
+passenv = {[testenv:system-tests]passenv} SPHINX_RELEASE READTHEDOCS LOCAL_RTD
 
 [pep8]
 exclude = gcloud/datastore/_datastore_v1_pb2.py,docs/conf.py