Re: Sphinx pre v3 -- removing support

[Akira Yokosawa <akiyks@gmail.com>]

[+Cc: Mauro]

On Fri, 3 Jun 2022 15:54:33 +0000,
Adam Turner wrote:
>>> 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.)

I might not be grasping the full context here, but I think the main script of
kernel documentation tool ./scripts/kernel-doc (a perl script) changes its
behavior depending on the target Sphinx version.

Its help text says:

>    Output format modifiers

>       reStructuredText only

>        -sphinx-version VERSION

>                Use the ReST C domain dialect compatible with a specific Sphinx

>                Version.


>
>                If not specified, kernel-doc will auto-detect using the

>                sphinx-build version found on PATH.

So it looks to me like it is already compatible with Sphinx 3.1 and later.

> 
> I don't want to be in the position of knowingly breaking the
> documentation tooling for the kernel. A strawman of a compromise
> would be for us (Sphinx) to delay the removal to Sphinx 7.0, and the
> kernel to increase the minimum to Sphinx 3.1 (required for
> ".. c:namespace::").

Yes, ".. c:namespace::" is actively used in userspace-api documentation.

FYI, see a recent reply from Mauro WRT support of kernel documentation
with different versions of Sphinx at:

  https://lore.kernel.org/linux-doc/20220521114629.6ee9fc06@coco.lan/

        Thanks, Akira


>                       That would enable the kernel to gradually update
> the syntax over a longer period, as I believe you won't be able to 
> use the v3 syntax currently.
> 
> Equally, Jonathan said he was hesitant to increase the minimum to 
> Sphinx 3, so perhaps that wouldn't work.
> 
> A