docs: add the list of component using a directive

docs/_extension/component_directive.py

@@ -0,0 +1,92 @@
+"""A directive to generate the list of all the built-in components.
+
+Read the content of the component folder and generate a list of all the components.
+This list will display some informations about the component and a link to the
+GitHub file.
+"""
+import re
+from pathlib import Path
+from typing import Any, Dict, List
+
+from docutils import nodes
+from sphinx.application import Sphinx
+from sphinx.util import logging
+from sphinx.util.docutils import SphinxDirective
+
+logger = logging.getLogger(__name__)
+
+TEMPLATE_LIST = '<ul class="simple">{content}</ul>'
+TEMPLATE_LINE = '<li><a href="{url}">{name}</a>:  {description}</li>'
+
+
+class ComponentListDirective(SphinxDirective):
+    """A directive to generate the list of all the built-in components.
+
+    Read the content of the component folder and generate a list of all the components.
+    This list will display some informations about the component and a link to the
+    GitHub file.
+    """
+
+    name = "component-list"
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = True
+
+    def run(self) -> List[nodes.Node]:
+        """Create the list."""
+        # get the list of all th jinja templates
+        # not that to remain compatible with sphinx they are labeled as html files
+        root = Path(__file__).parents[2]
+        component_dir = (
+            root
+            / "src"
+            / "pydata_sphinx_theme"
+            / "theme"
+            / "pydata_sphinx_theme"
+            / "components"
+        )
+        if not component_dir.is_dir():
+            raise FileNotFoundError(
+                f"Could not find component folder at {component_dir}."
+            )
+        components = sorted(component_dir.glob("*.html"))
+
+        # create the list of all the components description using bs4
+        # at the moment we use dummy information
+        docs = []
+        pattern = re.compile(r"(?<={#).*?(?=#})", flags=re.DOTALL)
+        for c in components:
+            comment = pattern.findall(c.read_text())
+            docs.append(comment[0].strip() if comment else "No description available.")
+
+        # get the urls from the github repo latest branch
+        github_url = "https://github.com/pydata/pydata-sphinx-theme/blob/main"
+        urls = [
+            f"{github_url}/{component.relative_to(root)}" for component in components
+        ]
+
+        # build the list of all the components
+        content = "".join(
+            TEMPLATE_LINE.format(name=component.stem, url=url, description=doc)
+            for component, url, doc in zip(components, urls, docs)
+        )
+
+        return [nodes.raw("", TEMPLATE_LIST.format(content=content), format="html")]
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+    """Add custom configuration to sphinx app.
+
+    Args:
+        app: the Sphinx application
+
+    Returns:
+        the 2 parallel parameters set to ``True``.
+    """
+    app.add_directive("component-list", ComponentListDirective)
+
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

docs/conf.py

@@ -35,6 +35,7 @@
     "sphinx_copybutton",
     "autoapi.extension",
     "_extension.gallery_directive",
+    "_extension.component_directive",
     # For extension examples and demos
     "ablog",
     "jupyter_sphinx",

docs/user_guide/layout.rst

@@ -517,29 +517,12 @@ Below is a list of built-in templates that you can insert into any section.
 Note that some of them may have CSS rules that assume a specific section (and
 will be named accordingly).
 
-.. refer to files in: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/
-
-- ``breadcrumbs.html``
-- ``copyright.html``
-- ``edit-this-page.html``
-- ``footer-article/prev-next.html``
-- ``icon-links.html``
-- ``last-updated.html``
-- ``navbar-icon-links.html``
-- ``navbar-logo.html``
-- ``navbar-nav.html``
-- ``page-toc.html``
-- ``searchbox.html``
-- ``search-button.html``
-- ``search-field.html``
-- ``sidebar-ethical-ads.html``
-- ``sidebar-nav-bs.html``
-- ``sourcelink.html``
-- ``sphinx-version.html``
-- ``theme-switcher.html``
-- ``version-switcher.html``
-- ``indices.html``
-- ``theme-version.html``
+.. note::
+
+    When adding/changing/overwritting a component, the ".html" suffix is optional.
+    That's why all of them are displayed without it in the following list.
+
+.. component-list::
 
 
 Add your own HTML templates to theme sections

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html

@@ -1,3 +1,4 @@
+{# Breadcrumb to display information on the navigation hierarchy. #}
 {%- block breadcrumbs %}
 {#
   If we have more than 3 parents (excluding the home page) then we remove

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html

@@ -1,3 +1,4 @@
+{# The component to display the copyrights informations set in conf.py. #}
 {% if show_copyright and copyright %}
   <p class="copyright">
     {% if hasdoc('copyright') %}

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/edit-this-page.html

@@ -1,3 +1,4 @@
+{# A link to the edit interface of the page source in the specified VCS. #}
 {% if sourcename is defined and theme_use_edit_page_button==true and page_source_suffix %}
   {% set src = sourcename.split('.') %}
   <div class="tocsection editthispage">

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/icon-links.html

@@ -1,3 +1,4 @@
+{# Display the icons link as inline blocks in the navbar. #}
 {%- macro icon_link_nav_item(url, icon, name, type, attributes='') -%}
   {%- if url | length > 2 %}
         <li class="nav-item">

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

@@ -1,3 +1,4 @@
+{# add the indies generated from Sphinx. #}
 <nav class="sidebar-indices-items">
   <p class="sidebar-indices-items__title" role="heading" aria-level="1">{{ _("Indices") }}</p>
   <ul class="indices-link">

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/last-updated.html

@@ -1,3 +1,4 @@
+{# Display the last time a page have been updated #}
 {%- if last_updated -%}
 <p class="last-updated">
   {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-icon-links.html

@@ -1,3 +1,4 @@
+{# Display the icons link as inline blocks in the navbar. #}
 {%- block icon_links -%}
   {%- include "icon-links.html" with context -%}
 {%- endblock icon_links %}

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html

@@ -1,3 +1,4 @@
+{# The logo of your documentation. #}
 {# Logo link generation -#}
 {% if not theme_logo.get("link") %}
   {% set href = pathto(root_doc) %}

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-nav.html

@@ -1,3 +1,4 @@
+{# The links of the first level toctree displayed in the header navbar. #}
 <nav class="navbar-nav">
   <p class="sidebar-header-items__title"
      role="heading"

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/page-toc.html

@@ -1,3 +1,4 @@
+{# Display the current page TOC.  #}
 {% set page_toc = generate_toc_html() %}
 {%- if page_toc | length >= 1 %}
   <div class="page-toc tocsection onthispage">

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/prev-next.html

@@ -1,4 +1,4 @@
-<!-- Previous / next buttons -->
+{# Previous / next buttons. #}
 <div class="prev-next-area">
   {%- if prev %}
     <a class="left-prev"

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html

@@ -1,7 +1,5 @@
-{# Behaves the same as `search-button.html` but looks more like a search field.
-  #
-  # As this function will only work when JavaScript is enabled, we add it through JavaScript.
-  #}
+{# Behaves the same as `search-button.html` but looks more like a search field. #}
+{# As this function will only work when JavaScript is enabled, we add it through JavaScript. #}
  <script>
  document.write(`
    <button class="btn navbar-btn search-button-field search-button__button" title="{{ _('Search') }}" aria-label="{{ _('Search') }}" data-bs-placement="bottom" data-bs-toggle="tooltip">

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html

@@ -1,7 +1,5 @@
-{# A button that, when clicked, will trigger a search popup overlay.
- #
- # As this function will only work when JavaScript is enabled, we add it through JavaScript.
- #}
+{# A button that, when clicked, will trigger a search popup overlay. #}
+{# As this function will only work when JavaScript is enabled, we add it through JavaScript. #}
 <script>
 document.write(`
   <button class="btn btn-sm navbar-btn search-button search-button__button" title="{{ _('Search') }}" aria-label="{{ _('Search') }}" data-bs-placement="bottom" data-bs-toggle="tooltip">

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-field.html

@@ -1,4 +1,4 @@
-{# A bootstrap-styled field that will direct to the `search.html` page when submitted #}
+{# A bootstrap-styled field that will direct to the `search.html` page when submitted. #}
 <form class="bd-search d-flex align-items-center"
       action="{{ pathto('search') }}"
       method="get">

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sidebar-ethical-ads.html

@@ -1,3 +1,4 @@
+{# Placeholder where the ReadTheDocs ethical ads will be placed. #}
 {% if READTHEDOCS %}
   <div id="ethical-ad-placement"
        class="flat"

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sidebar-nav-bs.html

@@ -1,3 +1,4 @@
+{# Add the toctree of each page included under the selected Heading 1 from header navbar. #}
 <nav class="bd-docs-nav bd-links"
      aria-label="{{ _('Section Navigation') }}">
   <p class="bd-links__title" role="heading" aria-level="1">{{ _("Section Navigation") }}</p>

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sourcelink.html

@@ -1,3 +1,4 @@
+{# If enabled, create a button to display the .rst source of the displayed page. #}
 {% if show_source and has_source and sourcename %}
   <div class="tocsection sourcelink">
     <a href="{{ pathto('_sources/' + sourcename, true)|e }}">

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sphinx-version.html

@@ -1,3 +1,4 @@
+{# Display the version of Sphinx used to build yout documentation. #}
 {% if show_sphinx %}
   <p class="sphinx-version">
     {% trans sphinx_version=sphinx_version|e %}Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html

@@ -1,5 +1,5 @@
-{# As the theme switcher will only work when JavaScript is enabled, we add it through JavaScript.
- #}
+{# A button to switch from one theme to another. Are currently supported: light, dark and auto. #}
+{# As the theme switcher will only work when JavaScript is enabled, we add it through JavaScript. #}
 <script>
 document.write(`
   <button class="btn btn-sm navbar-btn theme-switch-button" title="{{ _('light/dark') }}" aria-label="{{ _('light/dark') }}" data-bs-placement="bottom" data-bs-toggle="tooltip">

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html

@@ -1,3 +1,4 @@
+{# Display the version of the theme used to build the documentation. #}
 <p class="theme-version">
   {% trans theme_version=theme_version|e %}Built with the <a href="https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html">PyData Sphinx Theme</a> {{ theme_version }}.{% endtrans %}
 </p>

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/version-switcher.html

@@ -1,5 +1,5 @@
-{# As the version switcher will only work when JavaScript is enabled, we add it through JavaScript.
- #}
+{# A dropdown button to display the list of version available. These version need to be set in a switcher.json file. #}
+{# As the version switcher will only work when JavaScript is enabled, we add it through JavaScript. #}
 <script>
 document.write(`
   <div class="version-switcher__container dropdown">