feat: add the indices to the optional sidebar components (#922)

* add an indices component

* add indices.html to the list of component

* add an indices page

* Update docs/user_guide/indices.rst

Author: 12rambau

docs/user_guide/index.md

@@ -36,6 +36,7 @@ navigation
 page-toc
 header-links
 source-buttons
+indices
 ```
 
 ```{toctree}

docs/user_guide/indices.rst

@@ -0,0 +1,22 @@
+==============
+Sphinx indices
+==============
+
+Sphinx generates indices named `genindex`, `modindex` and `py-modindex` when building a documentation. More information about them can be found in the Sphinx documentation `here <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-index>`__.
+
+Add indices links
+=================
+
+By design the indices pages are not linked in a documentation generated with this theme. To include them in the left sidebar of each page, add the following configuration to your ``conf.py`` file in ``html_theme_options`` and the available indices will be display at the bottom.
+
+.. code-block:: python
+
+    html_theme_options = {
+        #[...]
+        "left_sidebar_end": ["indices.html", "sidebar-ethical-ads.html"]
+        #[...]
+    }
+
+.. note::
+
+    don't forget to add back the ``"sidebar-ethical-ads.html"`` template if you are serving your documentation using `ReadTheDocs <https://readthedocs.org>`__.

docs/user_guide/layout.rst

@@ -461,6 +461,7 @@ will be named accordingly).
 - ``sphinx-version.html``
 - ``theme-switcher.html``
 - ``version-switcher.html``
+- ``indices.html``
 
 
 Add your own HTML templates to theme sections

src/pydata_sphinx_theme/assets/styles/components/_indices.scss

@@ -0,0 +1,34 @@
+.sidebar-indices-items {
+  display: flex;
+  flex-direction: column;
+  border-top: 1px solid var(--pst-color-border);
+
+  @include media-breakpoint-up($breakpoint-sidebar-primary) {
+    border-top: none;
+  }
+
+  .sidebar-indices-items__title {
+    font-weight: var(--pst-sidebar-header-font-weight);
+    font-size: var(--pst-sidebar-header-font-size);
+    color: var(--pst-color-text-base);
+    margin-bottom: 0.5rem;
+  }
+
+  ul.indices-link {
+    margin-right: -1rem;
+    list-style: none;
+    padding: 0;
+
+    li > a {
+      display: block;
+      padding: 0.25rem 0;
+      color: var(--pst-color-text-muted);
+
+      &:hover {
+        color: var(--pst-color-primary);
+        text-decoration: none;
+        background-color: transparent;
+      }
+    }
+  }
+}

src/pydata_sphinx_theme/assets/styles/index.scss

@@ -54,6 +54,7 @@ $grid-breakpoints: (
 @import "./components/switcher-version";
 @import "./components/toc-inpage";
 @import "./components/versionmodified";
+@import "./components/indices";
 
 // Content blocks in standard Sphinx
 @import "./content/admonitions";

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/indices.html

@@ -0,0 +1,16 @@
+<nav class="sidebar-indices-items">
+  <p class="sidebar-indices-items__title" role="heading" aria-level="1">
+      {{ _("Indices") }}
+  </p>
+  <ul class="indices-link">
+    {%- for rellink in rellinks %}
+    {%- if rellink[0] == 'genindex' %}
+    <li class="toctree-l1"><a class="reference internal" href="{{ pathto('genindex') }}" accesskey="I">{{ _('General Index') }}</a></li>
+    {%- elif rellink[0] == 'modindex' %}
+    <li class="toctree-l1"><a class="reference internal" href="{{ pathto('modindex') }}">{{ _('Global Module Index') }}</a></li>
+    {%- elif rellink[0] == 'py-modindex' %}
+    <li class="toctree-l1"><a class="reference internal" href="{{ pathto('py-modindex') }}">{{ _('Python Module Index') }}</a></li>
+    {%- endif %}
+    {%- endfor %}
+  </ul>
+</nav>