-
-
Notifications
You must be signed in to change notification settings - Fork 7.9k
Update layout.html for sphinx themes #14893
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.
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
Conversation
Does this require a new version of Sphinx? If so, then that warrants a changelog entry. |
I don't think this requires a change in the sphinx version we use, but I did test it with 1.8.5 and I can test it with 1.8.1 (the minimum version we support) to be sure. |
The footer looks a bit different. Compare https://matplotlib.org/devdocs/api/_as_gen/matplotlib.pyplot.cla.html#matplotlib.pyplot.cla Probably the CSS does not trigger anymore. |
Thanks for the catch, @timhoffm – Indeed, the change had dropped a |
Note that this doesn't fix the issues in #13591 – that will have to come separately for full compatibility with Sphinx>=2 - but I'm thinking of trying to tackle that next. |
Also, I checked that this works just fine with |
<a href="http://sphinx-doc.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %} | ||
{%- endif %} | ||
{%- if sha %} | ||
Doc version {{ sha }}. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think, this should stay as well.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We need this because we build the docs from a different branch than the release.
<a href="http://sphinx-doc.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %} | ||
{%- endif %} | ||
{%- if sha %} | ||
Doc version {{ sha }}. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We need this because we build the docs from a different branch than the release.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks correct now.
Thanks! |
PR Summary
Matplotlib had a copy of the base sphinx theme
layout.html
– but this file was slowly getting out of sync with Sphinx.It turns out that Sphinx (and the default theme, alabaster) have added a lot of theming customization hooks, and it is possible to make the docs almost identical without carrying around an entire copy of
layout.html
. This allows matplotlib to take advantage of the maintenance done onlayout.html
by Sphinx upstream, without having to merge those changes occasionally into matplotlib itself.Here are some examples of the difference between generating the docs before and now:
<meta viewport=...
tag has been added.custom.css
is now emitted (this is harmless, but is the now supported way to provide CSS overrides to alabaster, the default sphinx theme).role=
, which should improve screen reader accessibility).<footer> <footer />
tag.As far as I can tell, there are no material differences to the way the docs look, but I would appreciate more eyes/further feedback.
PR Checklist
This isn't really a python change, so no tests are provided, and it shouldn't be user-facing (docs should look the same after this change) so I don't think it needs a "what's new" or "API changelog".