search

readthedocs / sphinx_rtd_theme

Sphinx theme from Read the Docs
https://sphinx-rtd-theme.readthedocs.io/
MIT License
4.81k stars 1.74k forks source link

Prepare for 3.0 release #1576

Closed humitos closed 3 months ago

humitos commented 4 months ago

This PR prepares the theme for the 3.0 release as planned in https://sphinx-rtd-theme.readthedocs.io/en/stable/development.html#roadmap-release-3-0-0

Related PRs I'd like to include here as well:

Closes #1570 Closes #1582 Closes #1559 Closes #1557

alex commented 4 months ago

Sphinx 8 was just released, it probably makes sense to try to include support for that here (assuming it's not an unreasonable amount of work).

zaufi commented 4 months ago

Sphinx 8 was just released…

And 2.0.0 version has a problem w/ it: #1571

humitos commented 4 months ago

Remove 'extra_css_files' #450

We should include a deprecation warning in 3.0, so we can remove it in 4.0 (from https://github.com/readthedocs/sphinx_rtd_theme/pull/450#issuecomment-1815040170). I agree with that 👍🏼

humitos commented 3 months ago

I did some QA here using master branch and this PR.

  1. Build from master 
    tox -e "py310-sphinx{62,72,latest,dev}"
  2. Build from this PR 
    tox -e "py310-sphinx{62,72,latest,dev}-qa"
  3. Open firefox and check for differences 
    firefox .tox/py310-sphinx72/tmp/html/demo/demo.html
firefox .tox/py310-sphinx72-qa/tmp/html/demo/demo.html
  4. Take a look at directory diff 
    diff -u .tox/py310-sphinx72/tmp/html/ .tox/py310-sphinx72-qa/tmp/html/

I haven't find any difference here, so I think we are good to go 👍🏼

After that, I switch to this PR in particular and run tox -e "py310-sphinx{62,74,80,latest,dev}" to find out differences between these versions but I found nothing. I'd say we are ready to move forward with a 3.0rc1 release after doing 2.1.0rc2 (see #1580)

humitos commented 3 months ago

I added a few extra commits to update the docs and add some deprecation warnings 👍🏼

agjohnson commented 3 months ago

Also, you don't mention this above, but if you aren't already you should also test multiple browsers and also test for tablet/mobile viewport. Chromium is fairly compatible with Firefox these days, Webkit usually gives the most unexpected results. Mobile and tablet viewport sizes mostly affect elements that require positioning, like footnotes, sidebar, and tables.

humitos commented 3 months ago

test multiple browsers and also test for tablet/mobile viewport

I did this and there are some differences. Depending on the "Dimensions" and "Rotation" it renders better in the old or new versions --but also it seems they are fixed in Sphinx 8.x (or even in the development branch) because I'm not able to reproduce them there. I think we can make a more extensive QA here as we go and open specific issues. I haven't found anything completely broken, tho, so I don't want to block moving forward with a release that supports Sphinx 8.x because of this.

I will merge this PR and release a 3.0.0rc1 so users can start using/testing it and report specific issues we can work on.

Currently, Sphinx 8.x users are getting 0.5.x version of the theme which is worse than that the current one -- even with this small issues on tablet/mobile issues.

alex commented 3 months ago

Great to hear @humitos , thanks!

agjohnson commented 3 months ago

@humitos Could you note the differences in an issue? We should follow up on these after an RC is out.

Styling does not frequently break completely, normally differences in docutils releases (and sometimes Sphinx) causes either changes in spacing, sizing, or positioning. Sometimes entire structures have changed (footnotes) and rendering is completely different.