Add an option to disable global TOC section

On some sites (like the governance site) the navigation between
pages is included in the page content itself, making the global
section of the TOC unnecessary. This adds a new theme option
(display_global_toc_section) to allow to disable it.

Change-Id: Ib6fb3bd1a6a776be06bc09e2e4183ca909ea7b60

doc/source/index.rst

@@ -158,6 +158,16 @@ can be disabled with the ``display_badge`` html theme option::
         # ...
     }
 
+The TOC on the left contains a global section (to navigate between pages)
+and a local section (showing page contents). If the TOC is diplayed in the
+text, you might want to disable the global section of the TOC::
+
+    html_theme_options = {
+        # ...
+        "display_global_toc_section": False,
+        # ...
+    }
+
 If you are using this theme for something other than docs.openstack.org,
 you can customize the root title ("OpenStack Docs") that appears in the
 page title and the left arrow tooltip::

openstackdocstheme/theme/openstackdocs/localtoc.html

@@ -1,7 +1,7 @@
 {%- if theme_sidebar_mode == 'toctree' and theme_display_toc and display_toc %}
   <div class="docs-sidebar-toc">
     <div class="docs-sidebar-section" id="local-table-of-contents">
-      <h4 class="docs-sidebar-section-title">Page Contents</h4>
+      <h4 class="docs-sidebar-section-title">{%- if theme_display_global_toc_section %}Page {%- endif %}Contents</h4>
       {{ toc }}
     </div>
   </div>

openstackdocstheme/theme/openstackdocs/sidebartoc.html

@@ -9,6 +9,7 @@
 {%- endif %}
   </div>
   <div class="docs-sidebar-toc">
+  {%- if theme_display_global_toc_section %}
     <div class="docs-sidebar-section" id="table-of-contents">
       <a href="{{ pathto(master_doc) }}" class="docs-sidebar-section-title"><h4>{{project}} {{version}}</h4></a>
       {%- if theme_sidebar_mode == 'toc' %}
@@ -17,6 +18,7 @@
       {{ toctree(maxdepth=2) }}
       {%- endif %}
     </div>
+  {%- endif %}
 {% include 'localtoc.html' %}
   </div>
 </div>

openstackdocstheme/theme/openstackdocs/theme.conf

@@ -8,6 +8,7 @@ analytics_tracking_code = UA-17511903-1
 sidebar_mode = toctree
 display_badge = True
 display_toc = True
+display_global_toc_section = True
 root_title = OpenStack Docs
 sidebar_dropdown = os_docs
 show_other_versions = False