Add Sphinx 7 support

[benjaoming]

• Remove -Dhtml4_writer=0 in build options that didn't seem necessary, builds are fine.

Fixes #1463

[humitos]

Did you find any visual difference or we are good to move forward?

[benjaoming]

@humitos That should be done, but I held back on systematic Q&A. We need a release plan, and I was hoping to have a more "combined" effort, so I opened up #1470

[potiuk]

It Would be great to get support for Sphinx 7, it holds us back in Airflow a bit :(

[mimi1vx]

fix for sphinx-7+ is pretty simple, but is incompatible with Sphinx older than 5.1

only needed change is https://github.com/readthedocs/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/layout.html#L28 , instead of style use styles[-1] :D

[benjaoming]

@mimi1vx this change should not be required because it's guarded by a version conditional:

sphinx_rtd_theme/sphinx_rtd_theme/layout.html

Lines 27 to 30 in cd6b429

	{%- if sphinx_version_info < (4, 0) -%}
	<link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
	<link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
	{%- endif %}

[mimi1vx]

Ah, i saw only older code , so it's need to update version guard + add new code path for 7.x

[agjohnson]

Yeah, agreed on that plan. I think incrementally bumping up our dependencies is still the right move. An RC is rather low stakes to release, so I'm a big fan of more frequently getting those out.

[agjohnson]

Anyone following along here, the new RC is out at https://pypi.org/project/sphinx-rtd-theme/1.3.0rc1/. You can install this with pip install --pre sphinx_rtd_theme

[alex]

Thanks! Is there any place to follow along for the final release?

[agjohnson]

@alex We'll mention anything major on our blog/newsletter and usually fediverse (we're not active on the bird/x site anymore).

Or for timely updates, PyPI has a great feature to monitor packages via RSS feed: https://pypi.org/rss/project/sphinx-rtd-theme/releases.xml

[alex]

Thanks

[potiuk]

Cool. On it :)

[potiuk]

The rc1 has also docutils < 0.19 which effectively blocks sphinx from being upgraded. Can it be changed as well?

[agjohnson]

@potiuk Not as easily, docutils is the source of most HTML output changes that affect the theme normally. Docutils 0.19 support is tracked at:

• Support for docutils 0.19.x #1323

But, you shouldn't need docutils 0.19 either. The specifier for Sphinx 7.0 and 7.1 is ¹: docutils>=0.18.1,<0.21

So you should be able to use docutils 0.18.1, unless there is something else going on.

Footnotes

1. https://github.com/sphinx-doc/sphinx/blob/320d0b631cc7d9617f5167cc61c9284674f5b2df/pyproject.toml#L65 ↩

[potiuk]

@potiuk Not as easily, docutils is the source of most HTML output changes that affect the theme normally. Docutils 0.19 support is tracked at:

Indeed - it was our limitation :) . On it, trying to see how far we are when we just build our docs with Sphinx 7 ... 🤞

[potiuk]

We are on a good way to migrate after this change. We already have CSS fixes needed to get back the look & feel needed after docutils bump. All looks good :)

[agjohnson]

@potiuk oh good, glad you were able to work around that. If you can share any changes you make on the CSS side for docutils 0.19/0.20, we'll be eventually making the same CSS changes here. It's usually obvious what changes, but it doesn't hurt to have some extra eyes on the style changes too.

[potiuk]

Well have them up soon in our repo - then I will (waiting for the CSS expert :D to submit a pr). And I am not sure it will be directly applicable. It's a customisation of our custom CSS that we changed already long time ago. I think the main difference is that docutils now produces a bitt different HTML for sections/headers etc. and the css that applied to the previous one did not apply to the new one. But I will share it regardless.

[agjohnson]

Ah gotcha. It might be useful still! No rush either way, we won't be jumping into docutils 0.2 support for a little bit.