Re: Sphinx pre v3 -- removing support

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

On Sat, 04 Jun 2022, Akira Yokosawa <akiyks@gmail.com> wrote:
> [+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.

That doesn't change my opinion that it would be best avoided! ;)

BR,
Jani.

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

-- 
Jani Nikula, Intel Open Source Graphics Center