docs: add the list of component using a directive (#1476)

* fix: create the component list automatically * fix: read the first comment as documentation * docs: add disclaimer on .html suffix * docs: document every component with a simple one liner * fix: use regex to identify comments * update component branch (#15) * Change default logo alt text (#1472) * Default logo alt text only if no extra text * change default logo * use docstitle as default logo alt text * update docs to reflect change * Apply suggestions from code review Co-authored-by: Daniel McCloy <dan@mccloy.info> * use string formatting operator * Update docs/user_guide/branding.rst * docs fixes * Update docs/user_guide/branding.rst * add test * Update pyproject.toml * revert to original --------- Co-authored-by: Daniel McCloy <dan@mccloy.info> Co-authored-by: Rambaud Pierrick <12rambau@users.noreply.github.com> * chore(i18n) catalan (#1488) i18n: Translate sphinx.po in ca 100% translated source file: 'sphinx.po' on 'ca'. Co-authored-by: transifex-integration[bot] <43880903+transifex-integration[bot]@users.noreply.github.com> * Build(deps): Bump postcss and css-loader (#1494) Bumps [postcss](https://github.com/postcss/postcss) to 8.4.31 and updates ancestor dependency [css-loader](https://github.com/webpack-contrib/css-loader). These dependencies need to be updated together. Updates `postcss` from 8.4.21 to 8.4.31 - [Release notes](https://github.com/postcss/postcss/releases) - [Changelog](https://github.com/postcss/postcss/blob/main/CHANGELOG.md) - [Commits](postcss/postcss@8.4.21...8.4.31) Updates `css-loader` from 3.6.0 to 6.8.1 - [Release notes](https://github.com/webpack-contrib/css-loader/releases) - [Changelog](https://github.com/webpack-contrib/css-loader/blob/master/CHANGELOG.md) - [Commits](webpack-contrib/css-loader@v3.6.0...v6.8.1) --- updated-dependencies: - dependency-name: postcss dependency-type: indirect - dependency-name: css-loader dependency-type: direct:development ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Revert "Build(deps): Bump postcss and css-loader" (#1509) Revert "Build(deps): Bump postcss and css-loader (#1494)" This reverts commit 185a37a. * Update pst docs buttons (#1502) * call them button-links * copy edit * docs: link back to GitHub from PyPI metadata (#1504) This will add a "Source" link in the PyPI page. * navigation_with_keys = False (#1503) * navigation_with_keys = False * None -> False * Apply suggestions from code review --------- Co-authored-by: Daniel McCloy <dan@mccloy.info> * fix: convert "stable" to actual version number (#1512) * convert "stable" to actual version number * fix tests re: navigation_with_keys * try bumping autoapi * refactor: use nbsphinx as the default execution lib (#1482) * refactor: use nbsphinx as the default execution lib * add nbstripout to the pre-commits' * add pandoc to the readthedocs deps * refactor: clean the notebook * move the example to the correct folder * fix: solve link issue * install pandoc in the test environment * fix: display of large table in executed cells * avoid Userwarnings from matplotlib * hide the matplotlib wrning management cell * Update readthedocs.yml * build: use pandoc_binary to install pandoc * docs: add reference to pandoc in the setup * update docs * remove pypandoc_binary * Update pyproject.toml Co-authored-by: gabalafou <gabriel@fouasnon.com> * ci: use back setup-pandoc * Trigger CI build --------- Co-authored-by: Gabriel Fouasnon <gabriel@fouasnon.com> * BUG - Clear alt_text in conf.py (#1471) * comment out alt_text in conf.py * set alt_text to empty string * remove alt_text from conf.py * fix: use 12rambau fork until it's merged with nikeee repo (#1517) * deps: drop support for Sphinx 5 (#1516) * remove ref to myst-nb * update minimal supported version of sphinx * Fix: (webpack.config.js) css-loader API change (#1508) * Fix: (webpack.config.js) css-loader API change The build was broken in <https://github.com/pydata/pydata-sphinx-theme/commit/185a37aa36820f77bffa4c87a772092e9e7cc380>/<https://github.com/pydata/pydata-sphinx-theme/pull/1494>. This change fixes the build, and it seems to be in accordance with the current API as described at <https://github.com/webpack-contrib/css-loader/blob/c6f36cf91ac61743a70e81cfb077faa0f8730ebe/README.md#boolean>. Closes <#1507>. * dedup * restore version bump --------- Co-authored-by: Daniel McCloy <dan@mccloy.info> * Fix duplicate HTML IDs (#1425) * Fix duplicate HTML IDs * fix tests * Do not animate the version admonitions colors. (#1424) Otherwise a delay has to be added to the accessibility color contrast checks, to wait for the colors to fully transition. * BUG - Remove redundant ARIA in breadcrumb navigation (#1426) * style(i18n): French Typo fixed (#1430) * Add the ability to add a center section to the footer (#1432) * Add a center section for the footer * Add docs for footer_center * Add a test site for the center footer * test it in our own docs * remove new test site * add footer test --------- Co-authored-by: Daniel McCloy <dan@mccloy.info> * Build(deps): Bump actions/checkout from 3 to 4 (#1433) Bumps [actions/checkout](https://github.com/actions/checkout) from 3 to 4. - [Release notes](https://github.com/actions/checkout/releases) - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md) - [Commits](actions/checkout@v3...v4) --- updated-dependencies: - dependency-name: actions/checkout dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Add dropdown_text argument to generate_header_nav_html (#1423) * Add dropdown_text argument to generate_header_nav_html * Add a test, fix typo in theme.conf and remove header_dropdown_text from docs/conf.py * fixed? --------- Co-authored-by: Daniel McCloy <dan@mccloy.info> * fix: rollback ref and Id changes (#1438) * bump: version 0.13.3 → 0.14.0 (#1440) * bump version * update version switcher * back to dev * fix: change the z-index of the dropdown (#1442) In order to be on top of the primary sidebar on small screens. * fix: set the same background for dark/light (#1443) * fix: set the same background for dark/light et the same background color for all state of the search field. It is currently only applied when hovered * fix: wrong css selector * Update src/pydata_sphinx_theme/assets/styles/components/_search.scss * Update src/pydata_sphinx_theme/assets/styles/components/_search.scss * Fix duplicate HTML IDs * fix tests * unique_html_id * backwards-compat generate_header_nav_html * feedback review * update fixture * ughhhh...caching * code cleanup * fix test snapshot * put comment inside def --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: Denis Bitouzé <dbitouze@wanadoo.fr> Co-authored-by: Stuart Mumford <stuart@cadair.com> Co-authored-by: Daniel McCloy <dan@mccloy.info> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Alenka Frim <AlenkaF@users.noreply.github.com> Co-authored-by: Rambaud Pierrick <12rambau@users.noreply.github.com> * chore: build the devcontainer automatically in codespace (#1483) * chore: build the devcontainer automaticallyin codespace * refactor: lint * add pandoc to the environment * Fix font color in search input box (#1524) * Fix color * Use --pst-color-text-base * docs: add DecentralChain (#1528) Co-authored-by: jourlez <josuecr.288@gmail.com> * Updates for file src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po in ru [Manual Sync] (#1527) i18n: Translate sphinx.po in ru [Manual Sync] 96% of minimum 20% translated source file: 'sphinx.po' on 'ru'. Sync of partially translated files: untranslated content is included with an empty translation or source language content depending on file format Co-authored-by: transifex-integration[bot] <43880903+transifex-integration[bot]@users.noreply.github.com> * ignore transient errors in windows build CI (#1520) * use warning list * clean up notebook * refactor to pass on all platforms? * simplify * fix logic * iterate backwards * fix plaform detection? also don't log unnecessarily�[H * ignore empty string warnings * remove notebook metawarning * Revert "remove notebook metawarning" This reverts commit 42f4672. * try again * debug the mysterious empty warning * escape color codes * import * triage by intermittency, not by platform; better var names * simplify * fix list.remove * undo what I broke * Update tests/utils/check_warnings.py * refactor: remove extention on component set-up (#1529) * use event.key for search shortcut (#1525) * use event.key for search shortcut * suggestions from review * caps lock --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: gabalafou <gabriel@fouasnon.com> Co-authored-by: Daniel McCloy <dan@mccloy.info> Co-authored-by: transifex-integration[bot] <43880903+transifex-integration[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Ned Batchelder <ned@nedbatchelder.com> Co-authored-by: Adam Porter <adam@alphapapa.net> Co-authored-by: Denis Bitouzé <dbitouze@wanadoo.fr> Co-authored-by: Stuart Mumford <stuart@cadair.com> Co-authored-by: Alenka Frim <AlenkaF@users.noreply.github.com> Co-authored-by: Harutaka Kawamura <hkawamura0130@gmail.com> Co-authored-by: jourlez <josuecr.288@gmail.com> * fix: use a directive instead of raw html * fix: make links externals * fix: set reference in paragraphs * fix: missing parameter * fix: use the stem for the component name * refactor: remove never used variables * standardize component descriptions --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: gabalafou <gabriel@fouasnon.com> Co-authored-by: Daniel McCloy <dan@mccloy.info> Co-authored-by: transifex-integration[bot] <43880903+transifex-integration[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Ned Batchelder <ned@nedbatchelder.com> Co-authored-by: Adam Porter <adam@alphapapa.net> Co-authored-by: Denis Bitouzé <dbitouze@wanadoo.fr> Co-authored-by: Stuart Mumford <stuart@cadair.com> Co-authored-by: Alenka Frim <AlenkaF@users.noreply.github.com> Co-authored-by: Harutaka Kawamura <hkawamura0130@gmail.com> Co-authored-by: jourlez <josuecr.288@gmail.com>
pydata · Nov 1, 2023 · fa456d0 · fa456d0
1 parent 2a469a8
commit fa456d0
Show file tree

Hide file tree

Showing 25 changed files with 132 additions and 38 deletions.
diff --git a/docs/_extension/component_directive.py b/docs/_extension/component_directive.py
@@ -0,0 +1,98 @@
+"""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__)
+
+
+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
+        items = []
+        for component, url, doc in zip(components, urls, docs):
+            items.append(
+                nodes.list_item(
+                    "",
+                    nodes.paragraph(
+                        "",
+                        "",
+                        nodes.reference("", component.stem, internal=False, refuri=url),
+                        nodes.Text(f": {doc}"),
+                    ),
+                )
+            )
+
+        return [nodes.bullet_list("", *items)]
+
+
+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,
+    }
diff --git a/docs/conf.py b/docs/conf.py
@@ -34,6 +34,9 @@
     "sphinx_design",
     "sphinx_copybutton",
     "autoapi.extension",
+    # custom extentions
+    "_extension.gallery_directive",
+    "_extension.component_directive",
     # For extension examples and demos
     "myst_parser",
     "ablog",
@@ -44,8 +47,6 @@
     "sphinx_togglebutton",
     "jupyterlite_sphinx",
     "sphinx_favicon",
-    # custom extentions
-    "_extension.gallery_directive",
 ]
 
 jupyterlite_config = "jupyterlite_config.json"

diff --git a/docs/user_guide/layout.rst b/docs/user_guide/layout.rst
@@ -518,29 +518,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

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html
@@ -1,3 +1,4 @@
+{# Displays (and links to) the parent section(s) of the currently viewed page. #}
 {%- block breadcrumbs %}
 {#
   If we have more than 3 parents (excluding the home page) then we remove

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/copyright.html
@@ -1,3 +1,4 @@
+{# Displays the copyright information (which is defined in conf.py). #}
 {% if show_copyright and copyright %}
   <p class="copyright">
     {% if hasdoc('copyright') %}

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/edit-this-page.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/edit-this-page.html
@@ -1,3 +1,4 @@
+{# Displays a link to the edit interface of the page source in the specified Version Control System. #}
 {% if sourcename is defined and theme_use_edit_page_button==true and page_source_suffix %}
   {% set src = sourcename.split('.') %}
   <div class="tocsection editthispage">

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/icon-links.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/icon-links.html
@@ -1,3 +1,4 @@
+{# Displays icon-links as list items. #}
 {%- macro icon_link_nav_item(url, icon, name, type, attributes='') -%}
   {%- if url | length > 2 %}
         <li class="nav-item">

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/indices.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/indices.html
@@ -1,3 +1,4 @@
+{# Displays links to the Sphinx-generated indices (genindex, modindex, py-modindex). #}
 <nav class="sidebar-indices-items">
   <p class="sidebar-indices-items__title" role="heading" aria-level="1">{{ _("Indices") }}</p>
   <ul class="indices-link">

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/last-updated.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/last-updated.html
@@ -1,3 +1,4 @@
+{# Displays the date and time that the documentation was last built. #}
 {%- if last_updated -%}
 <p class="last-updated">
   {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-icon-links.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-icon-links.html
@@ -1,3 +1,4 @@
+{# Displays icon-links in the header navbar. #}
 {%- block icon_links -%}
   {%- include "icon-links.html" with context -%}
 {%- endblock icon_links %}
diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
@@ -1,3 +1,4 @@
+{# Displays the logo of your documentation site, in the header navbar. #}
 {# Logo link generation -#}
 {% if not theme_logo.get("link") %}
   {% set href = pathto(root_doc) %}

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-nav.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-nav.html
@@ -1,3 +1,4 @@
+{# Displays links to the top-level TOCtree elements, in the header navbar. #}
 <nav class="navbar-nav">
   <p class="sidebar-header-items__title"
      role="heading"

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/page-toc.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/page-toc.html
@@ -1,3 +1,4 @@
+{# Displays the current page's Table of Contents.  #}
 {% set page_toc = generate_toc_html() %}
 {%- if page_toc | length >= 1 %}
   <div class="page-toc tocsection onthispage">

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/prev-next.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/prev-next.html
@@ -1,4 +1,4 @@
-<!-- Previous / next buttons -->
+{# Displays links to the previous and next page in the TOCtree order. #}
 <div class="prev-next-area">
   {%- if prev %}
     <a class="left-prev"

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button-field.html b/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.
-  #}
+{# Displays a search field image that opens a search overlay when clicked. #}
+{# 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">

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-button.html b/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.
- #}
+{# Displays a magnifying glass icon that opens a search overlay when clicked. #}
+{# 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">

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/search-field.html b/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 #}
+{# Displays an interactive search field directly on the page. #}
 <form class="bd-search d-flex align-items-center"
       action="{{ pathto('search') }}"
       method="get">

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/searchbox.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/searchbox.html
@@ -1,2 +1,2 @@
-{# div#searchbox hosts the "Hide Search Matches" link #}
+{# An empty container that holds the "Hide Search Matches" button when it's needed. #}
 <div id="searchbox"></div>
diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sidebar-ethical-ads.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sidebar-ethical-ads.html
@@ -1,3 +1,4 @@
+{# For sites hosted on ReadTheDocs, displays "ethical ads". #}
 {% if READTHEDOCS %}
   <div id="ethical-ad-placement"
        class="flat"

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sidebar-nav-bs.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sidebar-nav-bs.html
@@ -1,3 +1,4 @@
+{# Displays the TOC-subtree for pages nested under the currently active top-level TOCtree element. #}
 <nav class="bd-docs-nav bd-links"
      aria-label="{{ _('Section Navigation') }}">
   <p class="bd-links__title" role="heading" aria-level="1">{{ _("Section Navigation") }}</p>

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sourcelink.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sourcelink.html
@@ -1,3 +1,4 @@
+{# Displays a link to the .rst source of the current page. #}
 {% if show_source and has_source and sourcename %}
   <div class="tocsection sourcelink">
     <a href="{{ pathto('_sources/' + sourcename, true)|e }}">

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sphinx-version.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/sphinx-version.html
@@ -1,3 +1,4 @@
+{# Display the version of Sphinx used to build your 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 %}

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-switcher.html b/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.
- #}
+{# Displays an icon to switch between light mode, dark mode, and auto (use browser's setting). #}
+{# 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">

diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html
@@ -1,3 +1,4 @@
+{# Displays the version of pydata-sphinx-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>
diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/version-switcher.html b/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/version-switcher.html
@@ -1,3 +1,4 @@
+{# Displays a dropdown box for switching among different versions of your documentation. #}
 {%- set button_id = unique_html_id("pst-version-switcher-button") -%}
 {%- set dropdown_id = unique_html_id("pst-version-switcher-list") -%}
 {# As the version switcher will only work when JavaScript is enabled, we add it through JavaScript. #}