✨ NEW: hide sidebar + navbar_align option (#263)

Author: choldgraf

docs/conf.py

@@ -51,6 +51,7 @@
 
 html_sidebars = {
     "contributing": ["sidebar-search-bs.html", "custom-template.html"],
+    "changelog": [],
 }
 
 # -- Options for HTML output -------------------------------------------------
@@ -69,6 +70,7 @@
     "twitter_url": "https://twitter.com/pandas_dev",
     "use_edit_page_button": True,
     "show_toc_level": 1,
+    # "navbar_align": "right",  # For testing that the navbar items align properly
 }
 
 html_context = {

docs/user_guide/configuring.rst

@@ -48,6 +48,8 @@ an external site. You can add external links to the nav bar like so:
      ]
    }
 
+.. _configure-sidebar:
+
 Configure the sidebar
 =====================
 
@@ -180,3 +182,71 @@ You can show deeper levels by default by using the following configuration, indi
 
 All headings up to and including the level specified will now be shown
 regardless of what is displayed on the page.
+
+
+Remove the sidebar from some pages
+==================================
+
+If you'd like the left sidebar to be removed from a page, you can use the
+following configuration in ``conf.py``:
+
+.. code-block:: python
+
+   html_sidebars = {
+     "pagename": []
+   }
+
+This works for glob-style patterns as well. For example:
+
+.. code-block:: python
+
+   html_sidebars = {
+     "folder/*": []
+   }
+
+If you'd like to remove the left sidebar from **all** pages of your documentation,
+use this pattern:
+
+.. code-block:: python
+
+   html_sidebars = {
+     "**": []
+   }
+
+For information about configuring the sidebar's contents, see :ref:`configure-sidebar`.
+
+
+Configure navbar menu item alignment
+====================================
+
+By default, the navigation bar menu items will align with the content on your
+page. This equals the following default configuration:
+
+.. code-block:: python
+
+   html_theme_options = {
+      ...
+      "navbar_align_with_content": "content"
+      ...
+   }
+
+If instead you'd like these items to snap to the left (closer to the logo), use this
+configuration:
+
+.. code-block:: python
+
+   html_theme_options = {
+      ...
+      "navbar_align_with_content": "left"
+      ...
+   }
+
+If you'd like these items to snap to the right of the page, use this configuration:
+
+.. code-block:: python
+
+   html_theme_options = {
+      ...
+      "navbar_align_with_content": "right"
+      ...
+   }

pydata_sphinx_theme/__init__.py

@@ -75,8 +75,26 @@ def get_page_toc_object():
         except Exception:
             return {}
 
+    def navbar_align_class():
+        """Return the class that aligns the navbar based on config."""
+        align = context.get("theme_navbar_align", "content")
+        align_options = {
+            "content": ("col-lg-9", "mr-auto"),
+            "left": ("", "mr-auto"),
+            "right": ("", "ml-auto"),
+        }
+        if align not in align_options:
+            raise ValueError(
+                (
+                    "Theme optione navbar_align must be one of"
+                    f"{align_options.keys()}, got: {align}"
+                )
+            )
+        return align_options[align]
+
     context["get_nav_object"] = get_nav_object
     context["get_page_toc_object"] = get_page_toc_object
+    context["navbar_align_class"] = navbar_align_class
 
 
 def docutils_node_to_jinja(list_item, only_pages=False):

pydata_sphinx_theme/docs-navbar.html

@@ -11,9 +11,9 @@
     <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>
-
-    <div id="navbar-menu" class="col-lg-9 collapse navbar-collapse">
-      <ul id="navbar-main-elements" class="navbar-nav mr-auto">
+    {% 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 }}">
         {% set nav = get_nav_object(maxdepth=1, collapse=True) %}
         {% for main_nav_item in nav %}
         <li class="nav-item {% if main_nav_item.active%}active{% endif %}">

pydata_sphinx_theme/layout.html

@@ -45,11 +45,16 @@
     <div class="container-xl">
       <div class="row">
           {% block docs_sidebar %}
-          <div class="col-12 col-md-3 bd-sidebar">
-              {%- for sidebartemplate in sidebars %}
-              {%- include sidebartemplate %}
-              {%- endfor %}
-          </div>
+            {% if sidebars %}
+            <!-- Only show if we have sidebars configured, else just a small margin  -->
+            <div class="col-12 col-md-3 bd-sidebar">
+                {%- for sidebartemplate in sidebars %}
+                {%- include sidebartemplate %}
+                {%- endfor %}
+            </div>
+            {% else %}
+            <div class="col-12 col-md-1 col-xl-2 bd-sidebar no-sidebar"></div>
+            {% endif %}
           {% endblock %}
 
           {% block docs_toc %}
@@ -61,7 +66,12 @@
           {% endblock %}
 
           {% block docs_main %}
-          <main class="col-12 col-md-9 col-xl-7 py-md-5 pl-md-5 pr-md-4 bd-content" role="main">
+          {% if sidebars %}
+            {% set content_col_class = "col-md-9 col-xl-7" %}
+          {% else %}
+            {% set content_col_class = "col-md-11 col-xl-8" %}
+          {% endif %}
+          <main class="col-12 {{ content_col_class }} py-md-5 pl-md-5 pr-md-4 bd-content" role="main">
               {% block docs_body %}
               <div>
                 {% block body %} {% endblock %}

pydata_sphinx_theme/static/css/index.8bae7b2b42fe3a8dc942de8a456fc9f2.css renamed to pydata_sphinx_theme/static/css/index.c78d4f2b1f8277c2fa0830b4506d5cfe.css

@@ -17,13 +17,13 @@
 
 {% macro head_pre_bootstrap() %}
   <link href="{{ pathto('_static/css/theme.css', 1) }}" rel="stylesheet" />
-  <link href="{{ pathto('_static/css/index.8bae7b2b42fe3a8dc942de8a456fc9f2.css', 1) }}" rel="stylesheet" />
+  <link href="{{ pathto('_static/css/index.c78d4f2b1f8277c2fa0830b4506d5cfe.css', 1) }}" rel="stylesheet" />
 {% endmacro %}
 
 {% macro head_js_preload() %}
-  <link rel="preload" as="script" href="{{ pathto('_static/js/index.c3e2d73f727876cf7323.js', 1) }}">
+  <link rel="preload" as="script" href="{{ pathto('_static/js/index.8636327e669f6dcffc22.js', 1) }}">
 {% endmacro %}
 
 {% macro body_post() %}
-  <script src="{{ pathto('_static/js/index.c3e2d73f727876cf7323.js', 1) }}"></script>
+  <script src="{{ pathto('_static/js/index.8636327e669f6dcffc22.js', 1) }}"></script>
 {% endmacro %}

pydata_sphinx_theme/static/js/index.c3e2d73f727876cf7323.js renamed to pydata_sphinx_theme/static/js/index.8636327e669f6dcffc22.js

@@ -16,3 +16,4 @@ search_bar_text = Search the docs ...
 search_bar_position = sidebar
 navigation_with_keys = True
 show_toc_level = 1
+navbar_align = content

pydata_sphinx_theme/static/webpack-macros.html

@@ -210,6 +210,10 @@ table.field-list {
       height: calc(100vh - 4rem);
     }
   }
+
+  &.no-sidebar {
+    border-right: 0;
+  }
 }
 
 .bd-links {

pydata_sphinx_theme/theme.conf

@@ -97,3 +97,33 @@ def test_logo_name(file_regression, sphinx_build):
     sphinx_build.build(["-D", "html_logo="])
     index_html = sphinx_build.get("index.html")
     assert "PyData Tests" in index_html.select(".navbar-brand")[0].text.strip()
+
+
+def test_sidebar_visible(sphinx_build):
+    """The sidebar is shrunk when no sidebars specified in html_sidebars."""
+    sphinx_build.copy()
+
+    sphinx_build.build()
+    index_html = sphinx_build.get("page1.html")
+    assert "col-md-3" in index_html.select(".bd-sidebar")[0].attrs["class"]
+
+    sphinx_build.build(["-D", "html_sidebars.page1="])
+    index_html = sphinx_build.get("page1.html")
+    assert "col-md-1" in index_html.select(".bd-sidebar")[0].attrs["class"]
+    sphinx_build.clean()
+
+
+def test_navbar_align(sphinx_build):
+    """The navbar items align with the proper part of the page."""
+    sphinx_build.copy()
+
+    sphinx_build.build()
+    index_html = sphinx_build.get("index.html")
+    assert "col-lg-9" in index_html.select("div#navbar-menu")[0].attrs["class"]
+
+    # Both the column alignment and the margin should be changed
+    sphinx_build.build(["-D", "html_theme_options.navbar_align=right"])
+    index_html = sphinx_build.get("index.html")
+    assert "col-lg-9" not in index_html.select("div#navbar-menu")[0].attrs["class"]
+    assert "ml-auto" in index_html.select("ul#navbar-main-elements")[0].attrs["class"]
+    sphinx_build.clean()