Re: Sphinx pre v3 -- removing support

[Jani Nikula <jani.nikula@linux.intel.com>]

On Fri, 03 Jun 2022, Adam Turner <aaturnerpython@outlook.com> wrote:
>>> From Sphinx's perspective, we'd like to remove long-deprecated code.
>>> What is a good solution here for both sides? The intertial option is
>>> for us to delay the deprecation by another major version (removal is
>>> currently scheduled for Sphinx 6 (2023-05), and we are currently 
>>> releasing a major version every May.
>
>> So, can we assume that there won't be any backward-incompatible
>> behavior changes in Sphinx due to the removal of those long-deprecated
>> code?
>
> I'm referring to removing support for the "c_allow_pre_v3", 
> "c_warn_on_allowed_pre_v3", configuration options [1]_, and the 
> associated support for still parsing the pre v3 syntax in the C 
> domain [2]_. This means that pre v3 syntax in reStructuredText files
> would not work with Sphinx 6 onwards.
>
>> Or do you mean that after the release of Sphinx 6, pre v3 Sphinx
>> will be removed in the PyPI repository?
>
> No releases will be removed from PyPI, but if pre v3 syntax is still
> used, Sphinx 6.0 would fail to properly parse it.

And that's the crux of the problem. From kernel POV I'd very much prefer
not setting an upper bound for the Sphinx version. I think it's
important to be able to build the documentation using the latest Sphinx,
and gradually iron out the inevitable quirks that arise.

However, if you decide to drop support for pre v3 syntax in Sphinx v6,
and we decide to stick to being able to use pre v3 Sphinx, we can't move
forward to newer versions until we bump the lower bound for the Sphinx
version to v3+. (Or we need to hack around Sphinx version differences in
kernel, but I think that would be best avoided.)

BR,
Jani.


>
>> These questions might be too obvious for you but I have no idea what
>> you mean by "removing support".
>
> A
>
> _[1]: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-c_allow_pre_v3
> _[2]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-c-domain
>

-- 
Jani Nikula, Intel Open Source Graphics Center