Prepare for 3.0 release

[humitos]

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:

• Remove 'extra_css_files' #450
• Cleanup: Remove workaround/compatibility for old 0.3 version #1106
• Read READTHEDOCS_PROJECT from environment variables #1578
• Theme option flyout to enable/disable theme's flyout #1580
• Populate html_context with READTHEDOCS_* environment variables #1581
• Docs: do not install as Sphinx extension #1589
• Docs: update the installation note #1595

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

[alex]

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]

Sphinx 8 was just released…

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

[humitos]

Remove 'extra_css_files' #450

We should include a deprecation warning in 3.0, so we can remove it in 4.0 (from #450 (comment)). I agree with that 👍🏼

[humitos]

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]

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

[agjohnson]

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]

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]

Great to hear @humitos , thanks!

[agjohnson]

@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.