Skip to content

Commit

Permalink
docs: add the list of component using a directive (#1476)
Browse files Browse the repository at this point in the history
* 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>
  • Loading branch information
12 people authored Nov 1, 2023
1 parent 2a469a8 commit fa456d0
Show file tree
Hide file tree
Showing 25 changed files with 132 additions and 38 deletions.
98 changes: 98 additions & 0 deletions docs/_extension/component_directive.py
Original file line number Diff line number Diff line change
@@ -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,
}
5 changes: 3 additions & 2 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -44,8 +47,6 @@
"sphinx_togglebutton",
"jupyterlite_sphinx",
"sphinx_favicon",
# custom extentions
"_extension.gallery_directive",
]

jupyterlite_config = "jupyterlite_config.json"
Expand Down
29 changes: 6 additions & 23 deletions docs/user_guide/layout.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -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') %}
Expand Down
Original file line number Diff line number Diff line change
@@ -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">
Expand Down
Original file line number Diff line number Diff line change
@@ -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">
Expand Down
Original file line number Diff line number Diff line change
@@ -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">
Expand Down
Original file line number Diff line number Diff line change
@@ -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 %}
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
{# Displays icon-links in the header navbar. #}
{%- block icon_links -%}
{%- include "icon-links.html" with context -%}
{%- endblock icon_links %}
Original file line number Diff line number Diff line change
@@ -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) %}
Expand Down
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
Original file line number Diff line number Diff line change
@@ -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">
Expand Down
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
Original file line number Diff line number Diff line change
@@ -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">
Expand Down
Original file line number Diff line number Diff line change
@@ -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">
Expand Down
Original file line number Diff line number Diff line change
@@ -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">
Expand Down
Original file line number Diff line number Diff line change
@@ -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>
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
{# For sites hosted on ReadTheDocs, displays "ethical ads". #}
{% if READTHEDOCS %}
<div id="ethical-ad-placement"
class="flat"
Expand Down
Original file line number Diff line number Diff line change
@@ -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>
Expand Down
Original file line number Diff line number Diff line change
@@ -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 }}">
Expand Down
Original file line number Diff line number Diff line change
@@ -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 %}
Expand Down
Original file line number Diff line number Diff line change
@@ -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">
Expand Down
Original file line number Diff line number Diff line change
@@ -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>
Original file line number Diff line number Diff line change
@@ -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. #}
Expand Down

0 comments on commit fa456d0

Please sign in to comment.