Skip to content

Commit 6559c1a

Browse files
committed
Merge branch 'feature-focus' into header-nav-link-styles
2 parents 25323b7 + e054da1 commit 6559c1a

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

67 files changed

+684
-2000
lines changed
Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
"""A directive to generate the list of all the built-in components.
2+
3+
Read the content of the component folder and generate a list of all the components.
4+
This list will display some informations about the component and a link to the
5+
GitHub file.
6+
"""
7+
import re
8+
from pathlib import Path
9+
from typing import Any, Dict, List
10+
11+
from docutils import nodes
12+
from sphinx.application import Sphinx
13+
from sphinx.util import logging
14+
from sphinx.util.docutils import SphinxDirective
15+
16+
logger = logging.getLogger(__name__)
17+
18+
19+
class ComponentListDirective(SphinxDirective):
20+
"""A directive to generate the list of all the built-in components.
21+
22+
Read the content of the component folder and generate a list of all the components.
23+
This list will display some informations about the component and a link to the
24+
GitHub file.
25+
"""
26+
27+
name = "component-list"
28+
has_content = True
29+
required_arguments = 0
30+
optional_arguments = 0
31+
final_argument_whitespace = True
32+
33+
def run(self) -> List[nodes.Node]:
34+
"""Create the list."""
35+
# get the list of all th jinja templates
36+
# not that to remain compatible with sphinx they are labeled as html files
37+
root = Path(__file__).parents[2]
38+
component_dir = (
39+
root
40+
/ "src"
41+
/ "pydata_sphinx_theme"
42+
/ "theme"
43+
/ "pydata_sphinx_theme"
44+
/ "components"
45+
)
46+
if not component_dir.is_dir():
47+
raise FileNotFoundError(
48+
f"Could not find component folder at {component_dir}."
49+
)
50+
components = sorted(component_dir.glob("*.html"))
51+
52+
# create the list of all the components description using bs4
53+
# at the moment we use dummy information
54+
docs = []
55+
pattern = re.compile(r"(?<={#).*?(?=#})", flags=re.DOTALL)
56+
for c in components:
57+
comment = pattern.findall(c.read_text())
58+
docs.append(comment[0].strip() if comment else "No description available.")
59+
60+
# get the urls from the github repo latest branch
61+
github_url = "https://github.com/pydata/pydata-sphinx-theme/blob/main"
62+
urls = [
63+
f"{github_url}/{component.relative_to(root)}" for component in components
64+
]
65+
66+
# build the list of all the components
67+
items = []
68+
for component, url, doc in zip(components, urls, docs):
69+
items.append(
70+
nodes.list_item(
71+
"",
72+
nodes.paragraph(
73+
"",
74+
"",
75+
nodes.reference("", component.stem, internal=False, refuri=url),
76+
nodes.Text(f": {doc}"),
77+
),
78+
)
79+
)
80+
81+
return [nodes.bullet_list("", *items)]
82+
83+
84+
def setup(app: Sphinx) -> Dict[str, Any]:
85+
"""Add custom configuration to sphinx app.
86+
87+
Args:
88+
app: the Sphinx application
89+
90+
Returns:
91+
the 2 parallel parameters set to ``True``.
92+
"""
93+
app.add_directive("component-list", ComponentListDirective)
94+
95+
return {
96+
"parallel_read_safe": True,
97+
"parallel_write_safe": True,
98+
}

docs/_extension/gallery_directive.py

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ def run(self) -> List[nodes.Node]:
7575
path_doc = Path(path_doc).parent
7676
path_data = (path_doc / path_data_rel).resolve()
7777
if not path_data.exists():
78-
logger.warn(f"Could not find grid data at {path_data}.")
78+
logger.info(f"Could not find grid data at {path_data}.")
7979
nodes.text("No grid data found at {path_data}.")
8080
return
8181
yaml_string = path_data.read_text()
@@ -86,7 +86,6 @@ def run(self) -> List[nodes.Node]:
8686
# and generate a card item for each of them
8787
grid_items = []
8888
for item in safe_load(yaml_string):
89-
9089
# remove parameters that are not needed for the card options
9190
title = item.pop("title", "")
9291

docs/_static/custom.css

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,13 @@
77
div.admonition.admonition-olive {
88
border-color: hsl(60, 100%, 25%);
99
}
10-
div.admonition.admonition-olive > .admonition-title:before {
10+
div.admonition.admonition-olive > .admonition-title {
1111
background-color: hsl(60, 100%, 14%);
12+
color: white;
1213
}
1314
div.admonition.admonition-olive > .admonition-title:after {
1415
color: hsl(60, 100%, 25%);
1516
}
16-
div.admonition.admonition-olive > .admonition-title {
17-
color: white;
18-
}
1917
/* end-custom-color */
2018

2119
/* begin-custom-icon/* <your static path>/custom.css */
@@ -30,16 +28,14 @@ div.admonition.admonition-icon > .admonition-title:after {
3028
div.admonition.admonition-youtube {
3129
border-color: hsl(0, 100%, 50%); /* YouTube red */
3230
}
33-
div.admonition.admonition-youtube > .admonition-title:before {
31+
div.admonition.admonition-youtube > .admonition-title {
3432
background-color: hsl(0, 99%, 18%);
33+
color: white;
3534
}
3635
div.admonition.admonition-youtube > .admonition-title:after {
3736
color: hsl(0, 100%, 50%);
3837
content: "\f26c"; /* fa-solid fa-tv */
3938
}
40-
div.admonition.admonition-youtube > .admonition-title {
41-
color: white;
42-
}
4339
/* end-custom-youtube */
4440

4541
/* fix for project names that are parsed as links: the whole card is a link so

docs/_static/switcher.json

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44
"url": "https://pydata-sphinx-theme.readthedocs.io/en/latest/"
55
},
66
{
7-
"name": "0.14.2 (stable)",
8-
"version": "v0.14.2",
7+
"name": "0.14.3 (stable)",
8+
"version": "v0.14.3",
99
"url": "https://pydata-sphinx-theme.readthedocs.io/en/stable/",
1010
"preferred": true
1111
},

docs/conf.py

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,9 @@
3434
"sphinx_design",
3535
"sphinx_copybutton",
3636
"autoapi.extension",
37+
# custom extentions
38+
"_extension.gallery_directive",
39+
"_extension.component_directive",
3740
# For extension examples and demos
3841
"myst_parser",
3942
"ablog",
@@ -44,10 +47,10 @@
4447
"sphinx_togglebutton",
4548
"jupyterlite_sphinx",
4649
"sphinx_favicon",
47-
# custom extentions
48-
"_extension.gallery_directive",
4950
]
5051

52+
jupyterlite_config = "jupyterlite_config.json"
53+
5154
# Add any paths that contain templates here, relative to this directory.
5255
templates_path = ["_templates"]
5356

docs/examples/gallery.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ Thanks for your support!
3535
link: https://fairlearn.org/main/about/
3636
- title: Feature-engine
3737
link: https://feature-engine.readthedocs.io/
38-
- title: idtracker.ai
38+
- title: idtracker&period;ai
3939
link: https://idtracker.ai/
4040
- title: MegEngine
4141
link: https://www.megengine.org.cn/doc/stable/en/index.html

docs/index.md

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,11 @@ A clean, Bootstrap-based Sphinx theme by and for [the PyData community](https://
2121
- header: "{fas}`circle-half-stroke;pst-color-primary` Light / Dark theme"
2222
content: "Users can toggle between light and dark themes interactively."
2323
- header: "{fas}`palette;pst-color-primary` Customizable UI and themes"
24-
content: "Customize colors and branding with CSS variables, and build custom UIs with [Sphinx Design](user_guide/web-components)."
24+
content: "Customize colors and branding with CSS variables, and build custom UIs with [Sphinx Design components](user_guide/web-components)."
2525
- header: "{fab}`python;pst-color-primary` Supports PyData and Jupyter"
26-
content: "CSS and UI support for Jupyter extensions and PyData execution outputs."
27-
link: "examples/pydata.html"
26+
content: "CSS and UI support for [Jupyter extensions](examples/execution) and [PyData execution outputs](examples/pydata.ipynb)."
2827
- header: "{fas}`lightbulb;pst-color-primary` Example Gallery"
29-
content: "See our gallery of projects that use this theme."
30-
link: "examples/gallery.html"
28+
content: "See [our gallery](examples/gallery.md) of projects that use this theme."
3129
```
3230

3331
```{seealso}

docs/jupyterlite_config.json

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"LiteBuildConfig": {
3+
"Application": {
4+
"log_level": 40
5+
}
6+
}
7+
}

docs/user_guide/header-links.rst

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -145,6 +145,17 @@ Image icons
145145

146146
If you'd like to display an icon image that is not in the FontAwesome icons library,
147147
you may instead specify a URL or a path to a local image that will be used for the icon.
148+
You may also use ``.svg`` images as if they were FontAwesome with a little additional setup.
149+
150+
Bitmap image icons
151+
~~~~~~~~~~~~~~~~~~
152+
153+
For all bitmap image icons such as ``.png``, ``.jpg``, etc., you must specify ``type`` as local.
154+
155+
.. note::
156+
157+
All icon images with ``"type": "local"`` are inserted into the document using ``<img>`` tags.
158+
If you need features specific to objects in the ``svg`` class please see :ref:`svg image icons <svg-image-icons>`
148159

149160
**To display an image on the web**, use ``"type": "url"``, and provide a URL to an image in the ``icon`` value.
150161
For example:
@@ -188,6 +199,65 @@ For example:
188199

189200
Use ``.svg`` images for a higher-resolution output that behaves similarly across screen sizes.
190201

202+
.. _svg-image-icons:
203+
204+
SVG image icons
205+
~~~~~~~~~~~~~~~
206+
207+
In order to make use of the full feature set of ``.svg`` images provided by HTML you will need
208+
to set up the ``.svg`` to be used as a FontAwesome type icon. This is a fairly straightforward process:
209+
210+
#. Copy the contents of ``custom-icon.js`` - located within the ``docs`` tree - into an appropriate directory of your documentation
211+
source (typically ``source/js``) and rename the file however you like. Highlighted below are the lines which must be modified
212+
213+
.. code:: javascript
214+
215+
prefix: "fa-custom",
216+
iconName: "pypi",
217+
icon: [
218+
17.313, // viewBox width
219+
19.807, // viewBox height
220+
[], // ligature
221+
"e001", // unicode codepoint - private use area
222+
"m10.383 0.2-3.239 ...", // string definined SVG path
223+
],
224+
225+
226+
#. Update the following file contents:
227+
228+
#. ``iconName`` to be one of our choosing
229+
#. Change the viewbox height and width to match that of your icon
230+
#. Replace the SVG path string with the path which defines your custom icon
231+
232+
#. Add the relative path from your source directory to the custom javascript file to your ``conf.py``:
233+
234+
.. code:: python
235+
236+
html_js_files = [
237+
...
238+
"js/pypi-icon.js",
239+
...
240+
]
241+
242+
#. Set up the icon link in the ``html_theme_options`` as a FontAwesome icon:
243+
244+
.. code:: python
245+
246+
html_theme_options = [
247+
...
248+
"icon_links": [
249+
{
250+
"name": "PyPI",
251+
"url": "https://www.pypi.org",
252+
"icon": "fa-custom fa-pypi",
253+
"type": "fontawesome",
254+
},
255+
],
256+
...
257+
]
258+
259+
That's it, your icon will now be inserted with the ``<svg>`` tag and not ``<img>``! You can reference your custom FontAwesome icon in CSS using ``fa-<custom-name>``.
260+
191261
.. _icon-link-shortcuts:
192262

193263
Icon Link Shortcuts

docs/user_guide/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,5 +74,6 @@ accessibility
7474
analytics
7575
static_assets
7676
performance
77+
warnings
7778
readthedocs
7879
```

0 commit comments

Comments
 (0)