FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

Bump pydata-sphinx-theme by dstansby · Pull Request #27658 · matplotlib/matplotlib · GitHub

  1. matplotlib
  2. matplotlib

Repository navigation

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
jklymak merged 7 commits into from
Mar 7, 2024
Conversation 20 Commits 7 Checks 0 Files changed
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 .css  (1) .py  (1) .txt  (1) .yml  (2) All 4 file types selected
Only manifest files
Viewed files
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Unified
Split
Hide whitespace
Diff view
Unified
Split
Hide whitespace
2 changes: 1 addition & 1 deletion .circleci/config.yml
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
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"

dstansby Mar 5, 2024

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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.

timhoffm Mar 5, 2024 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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.

dstansby Mar 5, 2024

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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.

dstansby Mar 5, 2024

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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.

dstansby Mar 5, 2024

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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.

QuLogic Mar 5, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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.

dstansby Mar 5, 2024 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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?

timhoffm Mar 6, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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

dstansby Mar 6, 2024

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
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. */

dstansby Mar 5, 2024

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

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
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
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"],
Comment thread
dstansby marked this conversation as resolved.
"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
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
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
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
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
Back | FazBrowse Home | New Git URL