Re: [GIT PULL] Documentation for 6.8

[Akira Yokosawa]

On Fri, 12 Jan 2024 07:43:39 -0700, Jonathan Corbet wrote:
> [Adding Akira]

Thanks!

> 
> Linus Torvalds <torvalds@xxxxxxxxxxxxxxxxxxx> writes:
> 
>> On Mon, 8 Jan 2024 at 10:59, Jonathan Corbet <corbet@xxxxxxx> wrote:
>>>
>>> - The minimum Sphinx requirement has been raised to 2.4.4, following a
>>>   warning that was added in 6.2.
>>
>> Well, speaking of warnings, github now has this "dependabot" thing
>> that warns about bad minimum requirements due to tooling that has
>> security issues.
>>
>> And it warns about our "jinja2 < 3.1" requirement, because apparently
>> that can cause issues:
>>
>>   "The xmlattr filter in affected versions of Jinja accepts keys
>> containing spaces. XML/HTML attributes cannot contain spaces, as each
>> would then be interpreted as a separate attribute. If an application
>> accepts keys (as opposed to only values) as user input, and renders
>> these in pages that other users see as well, an attacker could use
>> this to inject other attributes and perform XSS. Note that accepting
>> keys as user input is not common or a particularly intended use case
>> of the xmlattr filter, and an application doing so should already be
>> verifying what keys are provided regardless of this fix"
>>
>> with affected versions being marked as < 3.1.3 and fixed in Jinja2 3.1.3
>>
>> I'm ignoring this github dependabit warning since the issue seems to
>> be rather irrelevant for our doc use, but I thought I'd mention it.
> 
> I suppose it is worth looking into this, just in case a hostile docs
> patch that nobody catches might somehow cause an exploit to show up on
> docs.kernel.org.  Seems unlikely but it would be good to be sure.
> 
> Akira (CC'd) noted, in adding that requirement, that newer jinja2 breaks
> Sphinx prior to 4.8.

There has never been a release "Sphinx 4.8".

What I said in [1] was:

 # jinja2>=3.1 is not compatible with Sphinx<4.0
 jinja2<3.1
-Sphinx==2.4.4
+# docutils>=0.18 is not compatible with 3.0 <= Sphinx < 4.0
+docutils<0.18
+Sphinx==3.4.3

So newer jinja2 and docutils break Sphinx prior to 4.0.

One more inconvenient truth Jon wouldn't like to know.

Official python 3.10 support was new to Sphinx 4.3.
So, I guess reasonable version for recommending is Sphinx>=4.3.

But at the same time, The latest Sphinx 7.2.6 works only with
python>=3.9.  If your base python3 is 3.8 (e.g. ubuntu 20.04),
you can't have the latest one.

Sounds very complicated, doesn't it?

I'm beginning to think that we can forget about those subtle
incompatibilities by recommending distro Sphinx packages.

As I summarized in [2], RHEL 9 and debian 11 have Sphinx 3.4.3,
which is good enough for kernel documentation.
Quoting from [2]:

              As of 2023.11.30

    ----------------------------------
    Distro              Sphinx Python3
    =================== ====== =======
    Ubuntu 22.04 LTS    4.3.2  3.10.12
    Debian 11           3.4.3  3.9.2
    Debian 12           5.3.0  3.11.2
    Fedora 39           6.2.1  3.12.0
    RHEL 9              3.4.3  3.9.18
    Mageia 9            6.1.3  3.10.11
    openSUSE Leap 15.5  4.2.0  3.6.15  (provided as python3-Sphinx_4_2_0)
    ----------------------------------

Installing one of those packages should come with compatible
requirements, plus several security fixes backported if we are
lucky.

There was a time when distro Sphinx was <2.4 and wasn't usable
for kernel documentation.  It is no longer true anymore.

[1]: https://lore.kernel.org/linux-doc/50830030-dca7-4c43-bcc8-449c7cfa9fbb@xxxxxxxxx/
[2]: https://lore.kernel.org/linux-doc/c3accd5b-c8d9-4eb9-86a1-054e89893a8f@xxxxxxxxx/

        Thanks, Akira


  I've been thinking that supporting 2.x is going to
> prove increasingly unsustainable, but raising our minimum to 4.8 would
> surely make some people unhappy.
> 
> I like the Python ecosystem for a lot of things, but its approach to API
> compatibility is ... not great.
> 
> jon