Skip to content

Bump pydata-sphinx-theme #27658

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Mar 7, 2024
Merged

Bump pydata-sphinx-theme #27658

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
13319f1
Bump pydata-sphinx-theme to 0.15
dstansby Jan 16, 2024
b68ed22
Fix search button placement in navbar
dstansby Jan 16, 2024
6f9eda7
Fix doc sidebar
dstansby Jan 16, 2024
bc2c872
Fix version switcher url for circleCI
dstansby Mar 4, 2024
591cd65
Don't use custom CSS for announcement banner
dstansby Mar 4, 2024
f178f5c
Disable parallel build
dstansby Mar 4, 2024
c908cd4
Don't show doc source link
dstansby Mar 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .circleci/config.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,7 @@ commands:
export RELEASE_TAG='-t release'
fi
mkdir -p logs
make html O="-T $RELEASE_TAG -j4 -w /tmp/sphinxerrorswarnings.log"
make html O="-T $RELEASE_TAG -j1 -w /tmp/sphinxerrorswarnings.log"
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change is because pydata-sphinx-theme doesn't support parallel writes: pydata/pydata-sphinx-theme#1643. It doesn't seem to impact build time significantly though, 18m19s before and 18m57s after.

Copy link
Member

@timhoffm timhoffm Mar 5, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not tested with the new version, but IIRC, I got significant speedups on my local machine with -j4. If we can't have that anymore, we need to update https://matplotlib.org/devdocs/devel/document.html#build-the-docs. Also, > 10min doc build times makes working on docs very unattractive. As somebody else said

In practice, that goes from "let me quickly build the docs to see the effect of this change" to "let's just hope it renders correctly".

Are the other improvements so significant that we are willing to take this on?

Edit: or is the above comparison old version -j4 vs. new version -j1. There were other performance improvements in the pydata Sphinx theme that might just compensate the losses of non-parallel builds.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The comparison is on circleCI between 591cd65 and f178f5c, the only difference being changing -j4 to -j1. Perhaps even with -j4 circleCI wasn't using any parallelism to build the docs?

Are the other improvements so significant that we are willing to take this on?

They include at least some accesibility improvements which I would advocate for.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that this is changing the parallel option only for the circleCI build, not any local or other builds, so the comparison using only times measured on circleCI is fair.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And you can still use parallel options, it will just raise a warning at the end of the doc build that pydata-sphinx-theme isn't parallel write safe.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see any need to change our call here. The theme marks it self as parallel-unsafe, so requesting parallel build will be turned off anyway. And then when they fix themselves, we'd need to remember to turn it back on again.

Copy link
Member Author

@dstansby dstansby Mar 5, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Without using -j1, shpinx emits a warning that the theme isn't parallel write safe, which fails the build. Ideally there would be a way to ignore just this warning and use -j4, but I'm not aware if that's possible with sphinx?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You could try to add a warnings filter to conf.py

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mean the suppress_warnings configuration? It seems to be the only relevant option to do this, but warning about a non-parallel write safe theme doesn't seem to be convered by the list of warning types that can be suppressed.

rm -r build/html/_sources
working_directory: doc
- save_cache:
Expand Down
23 changes: 0 additions & 23 deletions doc/_static/mpl.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,29 +14,6 @@
margin: 0;
}

/* Make announcement an error colour for unreleased documentation, and sticky. */
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This CSS interacts badly with dark mode, and removing it (and defaulting to what pydata-sphinx-theme uses) looks fine.

#unreleased-message.bd-header-announcement {
border-bottom: solid var(--pst-color-danger-highlight);
color: var(--pst-color-danger-text);
font-weight: var(--pst-admonition-font-weight-heading);
position: sticky;
top: 0;
z-index: 1050;
}

#unreleased-message.bd-header-announcement:after {
background-color: var(--pst-color-danger);
opacity: 1;
}

#unreleased-message.bd-header-announcement a {
color: var(--pst-color-danger-text);
}

#unreleased-message.bd-header-announcement + .bd-navbar {
top: 3rem; /* Minimum height of announcement header. */
}

/* multi column TOC */
.contents ul {
list-style-type: none;
Expand Down
14 changes: 12 additions & 2 deletions doc/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,7 @@ def _check_dependencies():
missing_references_write_json = False
missing_references_warn_unused_ignores = False


intersphinx_mapping = {
'Pillow': ('https://pillow.readthedocs.io/en/stable/', None),
'cycler': ('https://matplotlib.org/cycler/', None),
Expand Down Expand Up @@ -484,15 +485,21 @@ def js_tag_with_cache_busting(js):
# the server, but will be used as part of the key for caching by browsers
# so when we do a new meso release the switcher will update "promptly" on
# the stable and devdocs.
"json_url": f"https://matplotlib.org/devdocs/_static/switcher.json?{SHA}",
"json_url": (
"https://output.circle-artifacts.com/output/job/"
f"{os.environ['CIRCLE_WORKFLOW_JOB_ID']}/artifacts/"
f"{os.environ['CIRCLE_NODE_INDEX']}"
"/doc/build/html/_static/switcher.json" if CIRCLECI else
f"https://matplotlib.org/devdocs/_static/switcher.json?{SHA}"
),
"version_match": (
# The start version to show. This must be in switcher.json.
# We either go to 'stable' or to 'devdocs'
'stable' if matplotlib.__version_info__.releaselevel == 'final'
else 'devdocs')
},
"navbar_end": ["theme-switcher", "version-switcher", "mpl_icon_links"],
"secondary_sidebar_items": "page-toc.html",
"navbar_persistent": ["search-button"],
"footer_start": ["copyright", "sphinx-version", "doc_version"],
# We override the announcement template from pydata-sphinx-theme, where
# this special value indicates the use of the unreleased banner. If we need
Expand Down Expand Up @@ -543,6 +550,9 @@ def js_tag_with_cache_busting(js):
# '**': ['localtoc.html', 'pagesource.html']
}

# Don't include link to doc source files
html_show_sourcelink = False

# Copies only relevant code, not the '>>>' prompt
copybutton_prompt_text = r'>>> |\.\.\. '
copybutton_prompt_is_regexp = True
Expand Down
2 changes: 1 addition & 1 deletion environment.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ dependencies:
- ipywidgets
- numpydoc>=1.0
- packaging>=20
- pydata-sphinx-theme~=0.13.1
- pydata-sphinx-theme~=0.15.0
- pyyaml
- sphinx>=3.0.0,!=6.1.2
- sphinx-copybutton
Expand Down
2 changes: 1 addition & 1 deletion requirements/doc/doc-requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ ipywidgets
ipykernel
numpydoc>=1.0
packaging>=20
pydata-sphinx-theme~=0.13.1
pydata-sphinx-theme~=0.15.0
mpl-sphinx-theme~=3.8.0
pyyaml
sphinxcontrib-svg2pdfconverter>=1.1.0
Expand Down