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.

Author: dhermes

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;

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)

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>

docs/conf.py

@@ -11,10 +11,17 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+import os
 from pkg_resources import get_distribution
-import sys, os
+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.
@@ -36,7 +43,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'
@@ -100,10 +110,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

docs/index.rst

@@ -1,23 +1,48 @@
 .. toctree::
   :maxdepth: 0
   :hidden:
+  :caption: gcloud
 
   gcloud-api
+
+.. toctree::
+  :maxdepth: 0
+  :hidden:
+  :caption: Datastore
+
   datastore-overview
   datastore-client
   datastore-entities
   datastore-keys
   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
 
 

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