ENH: adding sphinx sidebars functionality (#248)

Author: choldgraf

docs/_templates/custom-template.html

@@ -0,0 +1,6 @@
+<div class="sidebar-message">
+    This is a community-supported theme.
+    If you'd like to contribute,
+    <a href="https://github.com/pandas-dev/pydata-sphinx-theme">check out our GitHub repository</a>
+    Your contributions are welcome!
+</div>

docs/conf.py

@@ -49,6 +49,9 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+html_sidebars = {
+    "contributing": ["sidebar-search-bs.html", "custom-template.html"],
+}
 
 # -- Options for HTML output -------------------------------------------------
 

docs/user_guide/configuring.rst

@@ -48,6 +48,17 @@ an external site. You can add external links to the nav bar like so:
      ]
    }
 
+Configure the sidebar
+=====================
+
+``pydata_sphinx_theme`` provides two new sidebar items by default:
+
+- ``sidebar-nav-bs.html`` - a bootstrap-friendly navigation section
+- ``sidebar-search-bs.html`` - a bootstrap-friendly search bar
+
+By default, this theme's sidebar has these two elements in it. If you'd like to
+override this behavior and control the sidebar on a per-page basis, use the
+`Sphinx html-sidebars configuration value <https://www.sphinx-doc.org/en/master/usage/configuration.html?highlight=html_sidebars#confval-html_sidebars>`_.
 
 Hiding the previous and next buttons
 ====================================

pydata_sphinx_theme/__init__.py

@@ -199,4 +199,9 @@ def setup(app):
     app.connect("html-page-context", setup_edit_url)
     app.connect("html-page-context", add_toctree_functions)
 
+    # Update templates for sidebar
+    pkgdir = os.path.abspath(os.path.dirname(__file__))
+    path_templates = os.path.join(pkgdir, "_templates")
+    app.config.templates_path.append(path_templates)
+
     return {"parallel_read_safe": True, "parallel_write_safe": True}

pydata_sphinx_theme/_templates/sidebar-nav-bs.html

@@ -0,0 +1,32 @@
+<nav class="bd-links" id="bd-docs-nav" aria-label="Main navigation">
+
+    <div class="bd-toc-item active">
+    {% set nav = get_nav_object(maxdepth=3, collapse=True) %}
+  
+    <ul class="nav bd-sidenav">
+        {% for main_nav_item in nav %}
+        {% if main_nav_item.active %}
+          {% for nav_item in main_nav_item.children %}
+            {% if nav_item.children %}
+  
+                <li class="{% if nav_item.active%}active{% endif %}">
+                    <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
+                    <ul>
+                    {% for nav_item in nav_item.children %}
+                        <li class="{% if nav_item.active%}active{% endif %}">
+                            <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
+                        </li>
+                    {% endfor %}
+                    </ul>
+                </li>
+            {% else %}
+                <li class="{% if nav_item.active%}active{% endif %}">
+                    <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
+                </li>
+            {% endif %}
+          {% endfor %}
+        {% endif %}
+        {% endfor %}
+      </ul>
+  
+  </nav>

pydata_sphinx_theme/_templates/sidebar-search-bs.html

@@ -0,0 +1,3 @@
+{% if theme_search_bar_position == "sidebar" %}
+  {%- include "search-field.html" %}
+{% endif %}

pydata_sphinx_theme/docs-sidebar.html

@@ -1,38 +0,0 @@
-
-
-{% if theme_search_bar_position == "sidebar" %}
-  {%- include "search-field.html" %}
-{% endif %}
-
-<nav class="bd-links" id="bd-docs-nav" aria-label="Main navigation">
-
-  <div class="bd-toc-item active">
-  {% set nav = get_nav_object(maxdepth=3, collapse=True) %}
-
-  <ul class="nav bd-sidenav">
-      {% for main_nav_item in nav %}
-      {% if main_nav_item.active %}
-        {% for nav_item in main_nav_item.children %}
-          {% if nav_item.children %}
-
-              <li class="{% if nav_item.active%}active{% endif %}">
-                  <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
-                  <ul>
-                  {% for nav_item in nav_item.children %}
-                      <li class="{% if nav_item.active%}active{% endif %}">
-                          <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
-                      </li>
-                  {% endfor %}
-                  </ul>
-              </li>
-          {% else %}
-              <li class="{% if nav_item.active%}active{% endif %}">
-                  <a href="{{ nav_item.url }}">{{ nav_item.title }}</a>
-              </li>
-          {% endif %}
-        {% endfor %}
-      {% endif %}
-      {% endfor %}
-    </ul>
-
-</nav>

pydata_sphinx_theme/layout.html

@@ -46,7 +46,9 @@
       <div class="row">
           {% block docs_sidebar %}
           <div class="col-12 col-md-3 bd-sidebar">
-              {%- include "docs-sidebar.html" %}
+              {%- for sidebartemplate in sidebars %}
+              {%- include sidebartemplate %}
+              {%- endfor %}
           </div>
           {% endblock %}
 

pydata_sphinx_theme/theme.conf

@@ -1,6 +1,7 @@
 [theme]
 inherit = basic
 pygments_style = tango
+sidebars = sidebar-search-bs.html, sidebar-nav-bs.html
 
 [options]
 sidebarwidth = 270

tests/sites/base/conf.py

@@ -18,3 +18,5 @@
 
 # Base options, we can add other key/vals later
 html_theme_options = {}
+
+html_sidebars = {"section1/index": ["sidebar-nav-bs.html"]}

tests/test_build/sidebar_subpage.html

@@ -1,9 +1,4 @@
 <div class="col-12 col-md-3 bd-sidebar">
- <form action="../search.html" class="bd-search d-flex align-items-center" method="get">
-  <i class="icon fas fa-search">
-  </i>
-  <input aria-label="Search the docs ..." autocomplete="off" class="form-control" id="search-input" name="q" placeholder="Search the docs ..." type="search"/>
- </form>
  <nav aria-label="Main navigation" class="bd-links" id="bd-docs-nav">
   <div class="bd-toc-item active">
    <ul class="nav bd-sidenav">