From fa456d0ea9fcfd4363f7af9cf43f7e84002d19eb Mon Sep 17 00:00:00 2001 From: Rambaud Pierrick <12rambau@users.noreply.github.com> Date: Wed, 1 Nov 2023 14:06:38 -0700 Subject: [PATCH] docs: add the list of component using a directive (#1476) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 * 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 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](https://github.com/postcss/postcss/compare/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](https://github.com/webpack-contrib/css-loader/compare/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] 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 185a37aa36820f77bffa4c87a772092e9e7cc380. * 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 * 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 * ci: use back setup-pandoc * Trigger CI build --------- Co-authored-by: Gabriel Fouasnon * 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 /. This change fixes the build, and it seems to be in accordance with the current API as described at . Closes . * dedup * restore version bump --------- Co-authored-by: Daniel McCloy * 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 * 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](https://github.com/actions/checkout/compare/v3...v4) --- updated-dependencies: - dependency-name: actions/checkout dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] 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 * 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] Co-authored-by: Denis Bitouzé Co-authored-by: Stuart Mumford Co-authored-by: Daniel McCloy Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Alenka Frim 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 * 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 * ignore empty string warnings * remove notebook metawarning * Revert "remove notebook metawarning" This reverts commit 42f46723eb9eeea7603efb91fbfb6bdfa1de28b3. * 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] Co-authored-by: gabalafou Co-authored-by: Daniel McCloy 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 Co-authored-by: Adam Porter Co-authored-by: Denis Bitouzé Co-authored-by: Stuart Mumford Co-authored-by: Alenka Frim Co-authored-by: Harutaka Kawamura Co-authored-by: jourlez * 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] Co-authored-by: gabalafou Co-authored-by: Daniel McCloy 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 Co-authored-by: Adam Porter Co-authored-by: Denis Bitouzé Co-authored-by: Stuart Mumford Co-authored-by: Alenka Frim Co-authored-by: Harutaka Kawamura Co-authored-by: jourlez --- docs/_extension/component_directive.py | 98 +++++++++++++++++++ docs/conf.py | 5 +- docs/user_guide/layout.rst | 29 ++---- .../components/breadcrumbs.html | 1 + .../components/copyright.html | 1 + .../components/edit-this-page.html | 1 + .../components/icon-links.html | 1 + .../components/indices.html | 1 + .../components/last-updated.html | 1 + .../components/navbar-icon-links.html | 1 + .../components/navbar-logo.html | 1 + .../components/navbar-nav.html | 1 + .../components/page-toc.html | 1 + .../components/prev-next.html | 2 +- .../components/search-button-field.html | 6 +- .../components/search-button.html | 6 +- .../components/search-field.html | 2 +- .../components/searchbox.html | 2 +- .../components/sidebar-ethical-ads.html | 1 + .../components/sidebar-nav-bs.html | 1 + .../components/sourcelink.html | 1 + .../components/sphinx-version.html | 1 + .../components/theme-switcher.html | 4 +- .../components/theme-version.html | 1 + .../components/version-switcher.html | 1 + 25 files changed, 132 insertions(+), 38 deletions(-) create mode 100644 docs/_extension/component_directive.py diff --git a/docs/_extension/component_directive.py b/docs/_extension/component_directive.py new file mode 100644 index 000000000..1749b0e7a --- /dev/null +++ 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 index fdcaec9bd..0a9076c64 100644 --- 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 index 7372ad980..f57cfd3b7 100644 --- 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 index c9e6f0438..8b5595bf3 100644 --- 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 index 8e1449d7d..b3e4f14e2 100644 --- 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 %}

{% 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 index 5bc0f1fca..fcfbf08ab 100644 --- 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('.') %}

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 index fe9faf52a..0b6ce64ad 100644 --- 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 %}
  • 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 index dc7090a78..73de5b33f 100644 --- 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). #}