Making navbar modular

docs/_templates/navbar-version.html

@@ -0,0 +1 @@
+v{{ version }}

docs/conf.py

@@ -21,9 +21,11 @@
 copyright = "2019, PyData Community"
 author = "PyData Community"
 
-# The full version, including alpha/beta/rc tags
-release = "0.0.1dev0"
+from pathlib import Path
 
+for ii in Path("../pydata_sphinx_theme/__init__.py").read_text().split("\n"):
+    if ii.startswith("__version__"):
+        version = release = ii.split("= ")[-1].strip('"').replace("dev0", "")
 
 # -- General configuration ---------------------------------------------------
 
@@ -50,7 +52,7 @@
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 html_sidebars = {
-    "contributing": ["sidebar-search-bs.html", "custom-template.html"],
+    "contributing": ["search-field.html", "custom-template.html"],
     "changelog": [],
 }
 
@@ -77,9 +79,11 @@
     ],
     "use_edit_page_button": True,
     "show_toc_level": 1,
-    # "navbar_align": "right",  # For testing that the navbar items align properly
+    # "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
+    "navbar_left": ["navbar-logo.html", "navbar-version.html"],
 }
 
+
 html_context = {
     "github_user": "pandas-dev",
     "github_repo": "pydata-sphinx-theme",

docs/user_guide/configuring.rst

@@ -129,7 +129,7 @@ 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
+- ``search-field.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
@@ -186,18 +186,34 @@ and you do not need to specify it if you wish to use the default.
 Configure the search bar position
 =================================
 
-To modify the position of the search bar, change the following variable in
-your configuration file ``conf.py``. Possible options are 'navbar' and 'sidebar'.
+To modify the position of the search bar, add the ``search-field.html``
+template to your **sidebar**, or to one of the **navbar** positions, depending
+on where you want it to be placed.
 
-By default the search bar is positioned in the sidebar since this is more
-suitable for large navigation bars.
+For example, if you'd like the search field to be in your side-bar, add it to
+the sidebar templates like so:
 
 .. code:: python
 
-    html_theme_options = {
-        "search_bar_position": "navbar"
+    html_sidebars = {
+        "**": ["search-field.html", "sidebar-nav-bs.html", "sidebar-ethical-ads.html"]
     }
 
+If instead you'd like to put the search bar in the top-right navbar, use the
+following configuration:
+
+.. code:: python
+
+   html_theme_options = {
+       "navbar_menu": ["navbar-menu-nav.html", "navbar-menu-buttons.html", "search-field.html"]
+   }
+
+
+.. note::
+
+   By default the search bar is positioned in the sidebar since this is more
+   suitable for large navigation bars.
+
 Configure the search bar text
 =============================
 
@@ -289,6 +305,65 @@ use this pattern:
 For information about configuring the sidebar's contents, see :ref:`configure-sidebar`.
 
 
+Configure the navbar items
+==========================
+
+You can choose which items show up in your navbar, as well as the order
+in which they appear. 
+
+Each menu item is a *template* in Sphinx, and you may
+add any template you wish to your navbar menu via configuring ``conf.py``.
+There are two navbar sections, corresponding to the following configuration
+values:
+
+.. code-block:: python
+
+   html_theme_options = {
+   ...
+   "navbar_left": ["list", "of", "templates"]  # Populates the left navbar
+   "navbar_menu": ["list", "of", "templates"]  # Populates the rest of the navbar
+   }
+
+By default, the following configuration is used:
+
+.. code-block:: python
+
+   html_theme_options = {
+   ...
+   "navbar_left": ["navbar-logo.html"],
+   "navbar_menu": ["navbar-menu-nav.html", "navbar-menu-search.html", "navbar-menu-buttons.html"],
+   ...
+   }
+
+If you'd like to add your own custom template to this list, you
+could do this with the following steps:
+
+1. Create an HTML file in a folder called ``_templates``. For example, if
+   you wanted to display the version of your documentation using a Jinja
+   template, you could create a file: ``_templates/version.html`` and put the
+   following in it:
+
+   .. code-block:: html
+
+      <!-- This will display the version of the docs -->
+      {{ version }}
+
+1. Now add the file to your menu items. For example:
+
+   .. code-block:: python
+
+      html_theme_options = {
+      ...
+      "navbar_left": ["version.html", "menu-logo.html"],
+      ...
+      }
+
+.. note::
+
+   Generally speaking, navbar menu items will be **right-aligned**. However, the
+   ``navbar-menu-nav.html`` template any anything that comes before it will
+   be **left-aligned**.
+
 Configure navbar menu item alignment
 ====================================
 
@@ -323,3 +398,22 @@ If you'd like these items to snap to the right of the page, use this configurati
       "navbar_align": "right"
       ...
    }
+
+
+Adding ethical advertisements to your sidebar in ReadTheDocs
+============================================================
+
+If you're hosting your documentation on ReadTheDocs, you should consider
+adding an explicit placement for their **ethical advertisements**. These are
+non-tracking advertisements from ethical companies, and they help ReadTheDocs
+sustain themselves and their free service.
+
+Ethical advertisements are added to your sidebar by default. To ensure they are
+there if you manually update your sidebar, ensure that the ``sidebar-ethical-ads.html``
+template is added to your list. For example:
+
+.. code:: python
+
+   html_sidebars = {
+       "**": ["search-field.html", "sidebar-nav-bs.html", "sidebar-ethical-ads.html"]
+   }

pydata_sphinx_theme/__init__.py

@@ -306,6 +306,11 @@ def get_edit_url():
     # Ensure that the max TOC level is an integer
     context["theme_show_toc_level"] = int(context.get("theme_show_toc_level", 1))
 
+    # Make sure the navbar menu items are a list
+    for section in ["theme_navbar_left", "theme_navbar_menu"]:
+        if isinstance(context[section], str):
+            context[section] = [ii.strip() for ii in context[section].split(",")]
+
 
 # -----------------------------------------------------------------------------
 

pydata_sphinx_theme/_templates/navbar-logo.html

@@ -0,0 +1,19 @@
+{% if logo %}
+{% if not theme_logo_link %}
+<a class="navbar-brand" href="{{ pathto(master_doc) }}">
+  <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="logo">
+</a>
+{% elif theme_logo_link[:4] == 'http' %}
+<a class="navbar-brand" href="{{ theme_logo_link }}">
+  <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="logo">
+</a>
+{% else %}
+<a class="navbar-brand" href="{{ pathto(theme_logo_link) }}">
+  <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="logo">
+</a>      
+{% endif %}
+{% else %}
+<a class="navbar-brand" href="{{ pathto(master_doc) }}">
+<p class="title">{{ project }}</p>
+</a>
+{% endif %}

pydata_sphinx_theme/_templates/navbar-menu-buttons.html

@@ -0,0 +1,3 @@
+{%- block icon_links -%}
+{%- include "icon-links.html" with context -%}
+{%- endblock %}

pydata_sphinx_theme/_templates/navbar-menu-nav.html

@@ -0,0 +1,8 @@
+<ul id="navbar-main-elements" class="navbar-nav {{ navbar_align }}">
+    {{ generate_nav_html("navbar", maxdepth=1, collapse=True, includehidden=True, titles_only=True) }}
+    {% for external_link in theme_external_links %}
+    <li class="nav-item">
+        <a class="nav-link nav-external" href="{{ external_link.url }}">{{ external_link.name }}<i class="fas fa-external-link-alt"></i></a>
+    </li>
+    {% endfor %}
+</ul>

pydata_sphinx_theme/_templates/sidebar-ethical-ads.html

@@ -0,0 +1,9 @@
+{% if READTHEDOCS %}
+<div
+  id="ethical-ad-placement"
+  class="flat"
+  data-ea-publisher="readthedocs"
+  data-ea-type="readthedocs-sidebar"
+  data-ea-manual="true"
+></div>
+{% endif %}

pydata_sphinx_theme/docs-navbar.html

@@ -1,47 +1,19 @@
 <div class="container-xl">
 
+  <div id="navbar-left">
+    {% for navbar_item in theme_navbar_left %}
+    {% include navbar_item %}
+    {% endfor %}
+  </div>
 
-    {% if logo %}
-      {% if not theme_logo_link %}
-      <a class="navbar-brand" href="{{ pathto(master_doc) }}">
-        <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="logo">
-      </a>
-      {% elif theme_logo_link[:4] == 'http' %}
-      <a class="navbar-brand" href="{{ theme_logo_link }}">
-        <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="logo">
-      </a>
-      {% else %}
-      <a class="navbar-brand" href="{{ pathto(theme_logo_link) }}">
-        <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="logo">
-      </a>      
-      {% endif %}
-    {% else %}
-    <a class="navbar-brand" href="{{ pathto(master_doc) }}">
-      <p class="title">{{ project }}</p>
-    </a>
-    {% endif %}
+  <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbar-menu" aria-controls="navbar-menu" aria-expanded="false" aria-label="Toggle navigation">
+    <span class="navbar-toggler-icon"></span>
+  </button>
 
-    <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbar-menu" aria-controls="navbar-menu" aria-expanded="false" aria-label="Toggle navigation">
-        <span class="navbar-toggler-icon"></span>
-    </button>
-
-    {% set navbar_class, navbar_align = navbar_align_class() %}
-    <div id="navbar-menu" class="{{ navbar_class }} collapse navbar-collapse">
-      <ul id="navbar-main-elements" class="navbar-nav {{ navbar_align }}">
-        {{ generate_nav_html("navbar", maxdepth=1, collapse=True, includehidden=True, titles_only=True) }}
-        {% for external_link in theme_external_links %}
-        <li class="nav-item">
-            <a class="nav-link nav-external" href="{{ external_link.url }}">{{ external_link.name }}<i class="fas fa-external-link-alt"></i></a>
-        </li>
-        {% endfor %}
-      </ul>
-
-      {% if theme_search_bar_position == 'navbar' %}
-        {%- include "search-field.html" %}
-      {% endif %}
-
-      {%- block icon_links -%}
-      {%- include "icon-links.html" with context -%}
-      {%- endblock %}
-    </div>
+  {% set navbar_class, navbar_align = navbar_align_class() %}
+  <div id="navbar-menu" class="{{ navbar_class }} collapse navbar-collapse">
+    {% for navbar_item in theme_navbar_menu %}
+    {% include navbar_item %}
+    {% endfor %}
+  </div>
 </div>

pydata_sphinx_theme/theme.conf

@@ -1,7 +1,7 @@
 [theme]
 inherit = basic
 pygments_style = tango
-sidebars = sidebar-search-bs.html, sidebar-nav-bs.html
+sidebars = search-field.html, sidebar-nav-bs.html, sidebar-ethical-ads.html
 
 [options]
 sidebarwidth = 270
@@ -21,3 +21,5 @@ search_bar_position = sidebar
 navigation_with_keys = True
 show_toc_level = 1
 navbar_align = content
+navbar_left = navbar-logo.html
+navbar_menu = navbar-menu-nav.html, navbar-menu-buttons.html