Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

[Jonathan Corbet]

Ming Wen <mwen@ambarella.com> writes:

> Dear Linux Doc’ers:
>
> Nice to e-meet you! And thanks for your great contribution to Linux
> Kernel world as always. 😊

To begin with, please do not send HTML mail, it won't make it through to
the lists.

> We’re now working on LTS Kernel 5.15 and 6.1. Recently, we’re trying
> to build their Sphinx Doc.

These are, of course, quite old kernels.

> It is required to go with Sphinx 2.4.4, which is much lower than the
> version(8.1.3) of ubuntu 22.04 and 24.04.

Required by who?  That is an ancient version of Sphinx at this point.

> PS: if going with very new version of Sphinx like 8.1.3, the final
> output is not right(doesn’t have the proper decoration).

Current Sphinx works fine, as far as I know; are there specific problems
that you can report with current kernels?

> To try to resolve this, we followed below way to build kernel Sphinx
> Doc by having Sphinx to stay with 2.4.4. However, it will require
> extra dependency packages(highlighted below in yellow) before we can
> build the doc properly.
>
> Here, we’d like to check with your comments for whether it will be
> good to merge it into the main branch for Kernel 5.15 and 6.1. If not,
> do you have any concern on this? Or you have other better
> options/advices for us to try? Thanks again for your time.

Again, those are very old kernels, that you are trying to make work with
a very old version of Sphinx.  I'm not sure why those patches would be
useful to anybody else?

> This email and attachments contain Ambarella Proprietary and/or Confidential
> Information and is intended solely for the use of the individual(s) to whom it is
> addressed. Any unauthorized review, use, disclosure, distribute, copy, or print is
> prohibited. If you are not an intended recipient, please contact the sender by reply email
> and destroy all copies of the original message. Thank you.

This, too, is not appropriate to send within our development community.

Thanks,

jon

RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

[Ming Wen]

Hi Jon:
 
Thanks for the quick response. And well noted for your highlights.

> We’re now working on LTS Kernel 5.15 and 6.1. Recently, we’re trying 
> to build their Sphinx Doc.
[Ming] Although they are old, they are still LTS versions. 😊


> It is required to go with Sphinx 2.4.4, which is much lower than the
> version(8.1.3) of ubuntu 22.04 and 24.04.
[Ming] To build the sphinx doc for Kernel 5.15 or 6.1, it is required to go with Sphinx 2.4.4.
Below is the python requirements.txt included in Kernel 5.15 and 6.1
$ cat Documentation/sphinx/requirements.txt
# jinja2>=3.1 is not compatible with Sphinx<4.0
jinja2<3.1
sphinx_rtd_theme
Sphinx==2.4.4


> Current Sphinx works fine, as far as I know; are there specific problems that you can report with current kernels?
[Ming] Could you give a try by building the sphinx doc for kernel 5.15 or kernel 6.1 using the default version Sphinx(like 8.1.3 ) on ubuntu 22.04 or 24.04?
I believe you will find surprise. 😊


> Again, those are very old kernels, that you are trying to make work with a very old version of Sphinx.  I'm not sure why those patches would be useful to anybody else?
[Ming] I definitely want to try with the latest Sphinx tool. But the kernel 5.15 or 6.1 requires us to use 2.4.4, which you think is a very old version of Sphinx.
We actually tried Sphinx 8.1.3 to build it for kernel 5.15 or 6.1. The output is not right (no proper decoration on the web GUI).


> This email and attachments contain Ambarella Proprietary and/or 
> Confidential Information and is intended solely for the use of the
> individual(s) to whom it is addressed. Any unauthorized review, use, 
> disclosure, distribute, copy, or print is prohibited. If you are not 
> an intended recipient, please contact the sender by reply email and destroy all copies of the original message. Thank you.
[Ming] Just checked with our IT members to get rid of it. Let me know if you still can see it.
 
Best Regards!
Ming Wen (闻明)
SDK Team | Ambarella Shanghai


-----Original Message-----
From: Jonathan Corbet <corbet@lwn.net> 
Sent: Wednesday, April 30, 2025 8:47 PM
To: Ming Wen <mwen@ambarella.com>; linux-doc@vger.kernel.org
Cc: mchehab@kernel.org; Long Li <longli@ambarella.com>; Jian Tang <jtang@ambarella.com>; Zhao-Yang Chen <zychen@ambarella.com>; Rongrong Cao <rrcao@ambarella.com>
Subject: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

Ming Wen <mwen@ambarella.com> writes:

> Dear Linux Doc’ers:
>
> Nice to e-meet you! And thanks for your great contribution to Linux 
> Kernel world as always. 😊

To begin with, please do not send HTML mail, it won't make it through to the lists.

> We’re now working on LTS Kernel 5.15 and 6.1. Recently, we’re trying 
> to build their Sphinx Doc.

These are, of course, quite old kernels.

> It is required to go with Sphinx 2.4.4, which is much lower than the
> version(8.1.3) of ubuntu 22.04 and 24.04.

Required by who?  That is an ancient version of Sphinx at this point.

> PS: if going with very new version of Sphinx like 8.1.3, the final 
> output is not right(doesn’t have the proper decoration).

Current Sphinx works fine, as far as I know; are there specific problems that you can report with current kernels?

> To try to resolve this, we followed below way to build kernel Sphinx 
> Doc by having Sphinx to stay with 2.4.4. However, it will require 
> extra dependency packages(highlighted below in yellow) before we can 
> build the doc properly.
>
> Here, we’d like to check with your comments for whether it will be 
> good to merge it into the main branch for Kernel 5.15 and 6.1. If not, 
> do you have any concern on this? Or you have other better 
> options/advices for us to try? Thanks again for your time.

Again, those are very old kernels, that you are trying to make work with a very old version of Sphinx.  I'm not sure why those patches would be useful to anybody else?

> This email and attachments contain Ambarella Proprietary and/or 
> Confidential Information and is intended solely for the use of the 
> individual(s) to whom it is addressed. Any unauthorized review, use, 
> disclosure, distribute, copy, or print is prohibited. If you are not 
> an intended recipient, please contact the sender by reply email and destroy all copies of the original message. Thank you.

This, too, is not appropriate to send within our development community.

Thanks,

jon

######################################################################
This EXTERNAL email has been scanned by Proofpoint Email Protect service.

**********************************************************************
This email and attachments contain Ambarella Proprietary and/or Confidential Information and is intended solely for the use of the individual(s) to whom it is addressed. Any unauthorized review, use, disclosure, distribute, copy, or print is prohibited. If you are not an intended recipient, please contact the sender by reply email and destroy all copies of the original message. Thank you.

RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

[Jonathan Corbet]

Ming Wen <mwen@ambarella.com> writes:

>> It is required to go with Sphinx 2.4.4, which is much lower than the
>> version(8.1.3) of ubuntu 22.04 and 24.04.
> [Ming] To build the sphinx doc for Kernel 5.15 or 6.1, it is required to go with Sphinx 2.4.4.

We recommended that version back then, mostly because the newer versions
were slower, but it is absolutely not required.

I just did the build for 6.134 using Sphinx 7.3.7.  It emits a bunch of
deprecation warnings, but otherwise works.

There are various fixes in mainline for some of those warnings; somebody
could certainly pick them out and ask for stable backports.  I can put
that onto my list of things to do, but won't get there in the next few
days.

Thanks,

jon

RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

[Ming Wen]

Hi Jon:
 
Perfect! Thanks for the quick trying.

When you built for 6.134 using Sphinx 7.3.7, did you have a chance to check the output of Sphinx doc? How about the web GUI? Does it look well with the expected decoration?
At our side, we can build the Sphinx doc successfully(although also with a lot of warning like you saw) if using Sphinx 8.1.3. But when looking at the web GUI, it is not right. The decoration is missing and the web link layout is also not good.
$ linux-5.15/Documentation/output/index.html 

If we switch back to Sphinx 2.4.4 following below method with extra dependencies added in requirements.txt, we can get the perfect web GUI decoration and layout.

$ /usr/bin/python3 -m venv sphinx_2.4.4
$ . sphinx_2.4.4/bin/activate
$ pip install -r ./Documentation/sphinx/requirements.txt

https://lore.kernel.org/lkml/50045aff-91f9-4809-ba3e-b722b325d233@oracle.com/T/
https://lore.kernel.org/lkml/20240226093854.47830-1-lukas.bulwahn@gmail.com/T/

diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
index 2c573541ab712..6e7ed641747f7 100644
--- a/Documentation/sphinx/requirements.txt
+++ b/Documentation/sphinx/requirements.txt
@@ -1,4 +1,10 @@
# jinja2>=3.1 is not compatible with Sphinx<4.0
jinja2<3.1
sphinx_rtd_theme
+alabaster<0.7.14
+sphinxcontrib-applehelp==1.0.4
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.5
Sphinx==2.4.4
 
Best Regards!
Ming Wen (闻明)
SDK Team | Ambarella Shanghai


-----Original Message-----
From: Jonathan Corbet <corbet@lwn.net> 
Sent: Wednesday, April 30, 2025 10:06 PM
To: Ming Wen <mwen@ambarella.com>; linux-doc@vger.kernel.org
Cc: mchehab@kernel.org; Long Li <longli@ambarella.com>; Jian Tang <jtang@ambarella.com>; Zhao-Yang Chen <zychen@ambarella.com>; Rongrong Cao <rrcao@ambarella.com>
Subject: RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

Ming Wen <mwen@ambarella.com> writes:

>> It is required to go with Sphinx 2.4.4, which is much lower than the
>> version(8.1.3) of ubuntu 22.04 and 24.04.
> [Ming] To build the sphinx doc for Kernel 5.15 or 6.1, it is required to go with Sphinx 2.4.4.

We recommended that version back then, mostly because the newer versions were slower, but it is absolutely not required.

I just did the build for 6.134 using Sphinx 7.3.7.  It emits a bunch of deprecation warnings, but otherwise works.

There are various fixes in mainline for some of those warnings; somebody could certainly pick them out and ask for stable backports.  I can put that onto my list of things to do, but won't get there in the next few days.

Thanks,

jon

**********************************************************************
This email and attachments contain Ambarella Proprietary and/or Confidential Information and is intended solely for the use of the individual(s) to whom it is addressed. Any unauthorized review, use, disclosure, distribute, copy, or print is prohibited. If you are not an intended recipient, please contact the sender by reply email and destroy all copies of the original message. Thank you.

RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

[Ming Wen]

Hi Jon:

Any update? Did you have a chance to check and comment on below?

Best Regards!
Ming Wen (闻明)
SDK Team | Ambarella Shanghai

-----Original Message-----
From: Ming Wen
Sent: Wednesday, April 30, 2025 11:16 PM
To: Jonathan Corbet <corbet@lwn.net>; linux-doc@vger.kernel.org
Cc: mchehab@kernel.org; Long Li <longli@ambarella.com>; Jian Tang <jtang@ambarella.com>; Zhao-Yang Chen <zychen@ambarella.com>; Rongrong Cao <rrcao@ambarella.com>
Subject: RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.
Importance: Low

Hi Jon:

Perfect! Thanks for the quick trying.

When you built for 6.134 using Sphinx 7.3.7, did you have a chance to check the output of Sphinx doc? How about the web GUI? Does it look well with the expected decoration?
At our side, we can build the Sphinx doc successfully(although also with a lot of warning like you saw) if using Sphinx 8.1.3. But when looking at the web GUI, it is not right. The decoration is missing and the web link layout is also not good.
$ linux-5.15/Documentation/output/index.html

If we switch back to Sphinx 2.4.4 following below method with extra dependencies added in requirements.txt, we can get the perfect web GUI decoration and layout.

$ /usr/bin/python3 -m venv sphinx_2.4.4
$ . sphinx_2.4.4/bin/activate
$ pip install -r ./Documentation/sphinx/requirements.txt

https://lore.kernel.org/lkml/50045aff-91f9-4809-ba3e-b722b325d233@oracle.com/T/
https://lore.kernel.org/lkml/20240226093854.47830-1-lukas.bulwahn@gmail.com/T/

diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
index 2c573541ab712..6e7ed641747f7 100644
--- a/Documentation/sphinx/requirements.txt
+++ b/Documentation/sphinx/requirements.txt
@@ -1,4 +1,10 @@
# jinja2>=3.1 is not compatible with Sphinx<4.0
jinja2<3.1
sphinx_rtd_theme
+alabaster<0.7.14
+sphinxcontrib-applehelp==1.0.4
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.5
Sphinx==2.4.4

Best Regards!
Ming Wen (闻明)
SDK Team | Ambarella Shanghai


-----Original Message-----
From: Jonathan Corbet <corbet@lwn.net>
Sent: Wednesday, April 30, 2025 10:06 PM
To: Ming Wen <mwen@ambarella.com>; linux-doc@vger.kernel.org
Cc: mchehab@kernel.org; Long Li <longli@ambarella.com>; Jian Tang <jtang@ambarella.com>; Zhao-Yang Chen <zychen@ambarella.com>; Rongrong Cao <rrcao@ambarella.com>
Subject: RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

Ming Wen <mwen@ambarella.com> writes:

>> It is required to go with Sphinx 2.4.4, which is much lower than the
>> version(8.1.3) of ubuntu 22.04 and 24.04.
> [Ming] To build the sphinx doc for Kernel 5.15 or 6.1, it is required to go with Sphinx 2.4.4.

We recommended that version back then, mostly because the newer versions were slower, but it is absolutely not required.

I just did the build for 6.134 using Sphinx 7.3.7.  It emits a bunch of deprecation warnings, but otherwise works.

There are various fixes in mainline for some of those warnings; somebody could certainly pick them out and ask for stable backports.  I can put that onto my list of things to do, but won't get there in the next few days.

Thanks,

jon

**********************************************************************
This email and attachments contain Ambarella Proprietary and/or Confidential Information and is intended solely for the use of the individual(s) to whom it is addressed. Any unauthorized review, use, disclosure, distribute, copy, or print is prohibited. If you are not an intended recipient, please contact the sender by reply email and destroy all copies of the original message. Thank you.

RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

[Rongrong Cao]

Ming,
This is a false alarm, Jon already committed the codes in 2021, but the LTS maintainer didn't merge it to LTS Kernel 5.15.
And here is the root cause and patch:
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/commit/Documentation/conf.py?id=d69dab7de208748ddf79143b39d98db55eee9b4a

Best Regards!
CRR

-----Original Message-----
From: Ming Wen <mwen@ambarella.com> 
Sent: Tuesday, May 6, 2025 18:40
To: Jonathan Corbet <corbet@lwn.net>; linux-doc@vger.kernel.org
Cc: mchehab@kernel.org; Long Li <longli@ambarella.com>; Jian Tang <jtang@ambarella.com>; Zhao-Yang Chen <zychen@ambarella.com>; Rongrong Cao <rrcao@ambarella.com>
Subject: RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.
Importance: Low

Hi Jon:
 
Any update? Did you have a chance to check and comment on below?
 
Best Regards!
Ming Wen (闻明)
SDK Team | Ambarella Shanghai

-----Original Message-----
From: Ming Wen 
Sent: Wednesday, April 30, 2025 11:16 PM
To: Jonathan Corbet <corbet@lwn.net>; linux-doc@vger.kernel.org
Cc: mchehab@kernel.org; Long Li <longli@ambarella.com>; Jian Tang <jtang@ambarella.com>; Zhao-Yang Chen <zychen@ambarella.com>; Rongrong Cao <rrcao@ambarella.com>
Subject: RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.
Importance: Low

Hi Jon:
 
Perfect! Thanks for the quick trying.

When you built for 6.134 using Sphinx 7.3.7, did you have a chance to check the output of Sphinx doc? How about the web GUI? Does it look well with the expected decoration?
At our side, we can build the Sphinx doc successfully(although also with a lot of warning like you saw) if using Sphinx 8.1.3. But when looking at the web GUI, it is not right. The decoration is missing and the web link layout is also not good.
$ linux-5.15/Documentation/output/index.html 

If we switch back to Sphinx 2.4.4 following below method with extra dependencies added in requirements.txt, we can get the perfect web GUI decoration and layout.

$ /usr/bin/python3 -m venv sphinx_2.4.4
$ . sphinx_2.4.4/bin/activate
$ pip install -r ./Documentation/sphinx/requirements.txt

https://lore.kernel.org/lkml/50045aff-91f9-4809-ba3e-b722b325d233@oracle.com/T/
https://lore.kernel.org/lkml/20240226093854.47830-1-lukas.bulwahn@gmail.com/T/

diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
index 2c573541ab712..6e7ed641747f7 100644
--- a/Documentation/sphinx/requirements.txt
+++ b/Documentation/sphinx/requirements.txt
@@ -1,4 +1,10 @@
# jinja2>=3.1 is not compatible with Sphinx<4.0
jinja2<3.1
sphinx_rtd_theme
+alabaster<0.7.14
+sphinxcontrib-applehelp==1.0.4
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.5
Sphinx==2.4.4
 
Best Regards!
Ming Wen (闻明)
SDK Team | Ambarella Shanghai


-----Original Message-----
From: Jonathan Corbet <corbet@lwn.net> 
Sent: Wednesday, April 30, 2025 10:06 PM
To: Ming Wen <mwen@ambarella.com>; linux-doc@vger.kernel.org
Cc: mchehab@kernel.org; Long Li <longli@ambarella.com>; Jian Tang <jtang@ambarella.com>; Zhao-Yang Chen <zychen@ambarella.com>; Rongrong Cao <rrcao@ambarella.com>
Subject: RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

Ming Wen <mwen@ambarella.com> writes:

>> It is required to go with Sphinx 2.4.4, which is much lower than the
>> version(8.1.3) of ubuntu 22.04 and 24.04.
> [Ming] To build the sphinx doc for Kernel 5.15 or 6.1, it is required to go with Sphinx 2.4.4.

We recommended that version back then, mostly because the newer versions were slower, but it is absolutely not required.

I just did the build for 6.134 using Sphinx 7.3.7.  It emits a bunch of deprecation warnings, but otherwise works.

There are various fixes in mainline for some of those warnings; somebody could certainly pick them out and ask for stable backports.  I can put that onto my list of things to do, but won't get there in the next few days.

Thanks,

jon

**********************************************************************
This email and attachments contain Ambarella Proprietary and/or Confidential Information and is intended solely for the use of the individual(s) to whom it is addressed. Any unauthorized review, use, disclosure, distribute, copy, or print is prohibited. If you are not an intended recipient, please contact the sender by reply email and destroy all copies of the original message. Thank you.

RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

[Ming Wen]

Hi Rongrong:
 
Thanks for the update. Good to know!
As the next, Jon may help to check a bit why this changelist is missed to be merged into LTS Kernel 5.15 and even LTS Kernel 6.1. It should definitely be needed.😊
 
Best Regards!
Ming Wen (闻明)
SDK Team | Ambarella Shanghai

-----Original Message-----
From: Rongrong Cao <rrcao@ambarella.com> 
Sent: Wednesday, May 7, 2025 6:12 PM
To: Ming Wen <mwen@ambarella.com>; Jonathan Corbet <corbet@lwn.net>; linux-doc@vger.kernel.org
Cc: mchehab@kernel.org; Long Li <longli@ambarella.com>; Jian Tang <jtang@ambarella.com>; Zhao-Yang Chen <zychen@ambarella.com>
Subject: RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

Ming,
This is a false alarm, Jon already committed the codes in 2021, but the LTS maintainer didn't merge it to LTS Kernel 5.15.
And here is the root cause and patch:
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/commit/Documentation/conf.py?id=d69dab7de208748ddf79143b39d98db55eee9b4a

Best Regards!
CRR

-----Original Message-----
From: Ming Wen <mwen@ambarella.com> 
Sent: Tuesday, May 6, 2025 18:40
To: Jonathan Corbet <corbet@lwn.net>; linux-doc@vger.kernel.org
Cc: mchehab@kernel.org; Long Li <longli@ambarella.com>; Jian Tang <jtang@ambarella.com>; Zhao-Yang Chen <zychen@ambarella.com>; Rongrong Cao <rrcao@ambarella.com>
Subject: RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.
Importance: Low

Hi Jon:
 
Any update? Did you have a chance to check and comment on below?
 
Best Regards!
Ming Wen (闻明)
SDK Team | Ambarella Shanghai

-----Original Message-----
From: Ming Wen 
Sent: Wednesday, April 30, 2025 11:16 PM
To: Jonathan Corbet <corbet@lwn.net>; linux-doc@vger.kernel.org
Cc: mchehab@kernel.org; Long Li <longli@ambarella.com>; Jian Tang <jtang@ambarella.com>; Zhao-Yang Chen <zychen@ambarella.com>; Rongrong Cao <rrcao@ambarella.com>
Subject: RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.
Importance: Low

Hi Jon:
 
Perfect! Thanks for the quick trying.

When you built for 6.134 using Sphinx 7.3.7, did you have a chance to check the output of Sphinx doc? How about the web GUI? Does it look well with the expected decoration?
At our side, we can build the Sphinx doc successfully(although also with a lot of warning like you saw) if using Sphinx 8.1.3. But when looking at the web GUI, it is not right. The decoration is missing and the web link layout is also not good.
$ linux-5.15/Documentation/output/index.html 

If we switch back to Sphinx 2.4.4 following below method with extra dependencies added in requirements.txt, we can get the perfect web GUI decoration and layout.

$ /usr/bin/python3 -m venv sphinx_2.4.4
$ . sphinx_2.4.4/bin/activate
$ pip install -r ./Documentation/sphinx/requirements.txt

https://lore.kernel.org/lkml/50045aff-91f9-4809-ba3e-b722b325d233@oracle.com/T/
https://lore.kernel.org/lkml/20240226093854.47830-1-lukas.bulwahn@gmail.com/T/

diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
index 2c573541ab712..6e7ed641747f7 100644
--- a/Documentation/sphinx/requirements.txt
+++ b/Documentation/sphinx/requirements.txt
@@ -1,4 +1,10 @@
# jinja2>=3.1 is not compatible with Sphinx<4.0
jinja2<3.1
sphinx_rtd_theme
+alabaster<0.7.14
+sphinxcontrib-applehelp==1.0.4
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.5
Sphinx==2.4.4
 
Best Regards!
Ming Wen (闻明)
SDK Team | Ambarella Shanghai


-----Original Message-----
From: Jonathan Corbet <corbet@lwn.net> 
Sent: Wednesday, April 30, 2025 10:06 PM
To: Ming Wen <mwen@ambarella.com>; linux-doc@vger.kernel.org
Cc: mchehab@kernel.org; Long Li <longli@ambarella.com>; Jian Tang <jtang@ambarella.com>; Zhao-Yang Chen <zychen@ambarella.com>; Rongrong Cao <rrcao@ambarella.com>
Subject: RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

Ming Wen <mwen@ambarella.com> writes:

>> It is required to go with Sphinx 2.4.4, which is much lower than the
>> version(8.1.3) of ubuntu 22.04 and 24.04.
> [Ming] To build the sphinx doc for Kernel 5.15 or 6.1, it is required to go with Sphinx 2.4.4.

We recommended that version back then, mostly because the newer versions were slower, but it is absolutely not required.

I just did the build for 6.134 using Sphinx 7.3.7.  It emits a bunch of deprecation warnings, but otherwise works.

There are various fixes in mainline for some of those warnings; somebody could certainly pick them out and ask for stable backports.  I can put that onto my list of things to do, but won't get there in the next few days.

Thanks,

jon

**********************************************************************
This email and attachments contain Ambarella Proprietary and/or Confidential Information and is intended solely for the use of the individual(s) to whom it is addressed. Any unauthorized review, use, disclosure, distribute, copy, or print is prohibited. If you are not an intended recipient, please contact the sender by reply email and destroy all copies of the original message. Thank you.

RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

[Jonathan Corbet]

Ming Wen <mwen@ambarella.com> writes:

> Hi Rongrong:
>  
> Thanks for the update. Good to know!
> As the next, Jon may help to check a bit why this changelist is missed to be merged into LTS Kernel 5.15 and even LTS Kernel 6.1. It should definitely be needed.😊

The stable maintainers need to be told to apply a patch like this, and
nobody did that.  I will try to have a look in the near future to decide
whether that should be done in this case...sorry, I'm on the road, and
have a few balls to juggle at the moment.

jon

RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

[Rongrong Cao]

Linus said, 'Show me the code.' The actual meaning is that engineers will track the issue from the source code rather than from the documentation, and that's the reason why nobody complains about the documentation issue.

Thanks!
Best Regards!
CRR

-----Original Message-----
From: Jonathan Corbet <corbet@lwn.net> 
Sent: 2025年5月8日 4:03
To: Ming Wen <mwen@ambarella.com>; Rongrong Cao <rrcao@ambarella.com>; linux-doc@vger.kernel.org
Cc: mchehab@kernel.org; Long Li <longli@ambarella.com>; Jian Tang <jtang@ambarella.com>; Zhao-Yang Chen <zychen@ambarella.com>
Subject: RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

Ming Wen <mwen@ambarella.com> writes:

> Hi Rongrong:
>  
> Thanks for the update. Good to know!
> As the next, Jon may help to check a bit why this changelist is missed 
> to be merged into LTS Kernel 5.15 and even LTS Kernel 6.1. It should 
> definitely be needed.😊

The stable maintainers need to be told to apply a patch like this, and nobody did that.  I will try to have a look in the near future to decide whether that should be done in this case...sorry, I'm on the road, and have a few balls to juggle at the moment.

jon

**********************************************************************
This email and attachments contain Ambarella Proprietary and/or Confidential Information and is intended solely for the use of the individual(s) to whom it is addressed. Any unauthorized review, use, disclosure, distribute, copy, or print is prohibited. If you are not an intended recipient, please contact the sender by reply email and destroy all copies of the original message. Thank you.

RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

[Ming Wen]

Hi Jon:
 
Sounds good. Take your time~~
Keep us posted if you have a chance to move ahead a bit on your road. 😊
 
Best Regards!
Ming Wen (闻明)
SDK Team | Ambarella Shanghai


-----Original Message-----
From: Jonathan Corbet <corbet@lwn.net> 
Sent: Thursday, May 8, 2025 4:03 AM
To: Ming Wen <mwen@ambarella.com>; Rongrong Cao <rrcao@ambarella.com>; linux-doc@vger.kernel.org
Cc: mchehab@kernel.org; Long Li <longli@ambarella.com>; Jian Tang <jtang@ambarella.com>; Zhao-Yang Chen <zychen@ambarella.com>
Subject: RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

Ming Wen <mwen@ambarella.com> writes:

> Hi Rongrong:
>  
> Thanks for the update. Good to know!
> As the next, Jon may help to check a bit why this changelist is missed 
> to be merged into LTS Kernel 5.15 and even LTS Kernel 6.1. It should 
> definitely be needed.😊

The stable maintainers need to be told to apply a patch like this, and nobody did that.  I will try to have a look in the near future to decide whether that should be done in this case...sorry, I'm on the road, and have a few balls to juggle at the moment.

jon

**********************************************************************
This email and attachments contain Ambarella Proprietary and/or Confidential Information and is intended solely for the use of the individual(s) to whom it is addressed. Any unauthorized review, use, disclosure, distribute, copy, or print is prohibited. If you are not an intended recipient, please contact the sender by reply email and destroy all copies of the original message. Thank you.

RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

[Jonathan Corbet]

Ming Wen <mwen@ambarella.com> writes:

> Thanks for the update. Good to know!

> As the next, Jon may help to check a bit why this changelist is missed
> to be merged into LTS Kernel 5.15 and even LTS Kernel 6.1. It should
> definitely be needed.😊

So I have *finally* had a chance to take a look at this.  For 5.15, I
can certainly ask that commit d69dab7de208 be backported (I'll note that
anybody else can do that too).  BUT: that commit was applied to 5.16, so
if there are problems with 6.1, they lie elsewhere.  That makes me
suspect that this commit isn't the one we're looking for?

jon

RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

[Ming Wen]

Hi Jon:
 
Thanks for taking care of this.
I double checked again 6.1.
You're right. Your commit was merged already. And it was later on refined a bit by "Mauro Carvalho Chehab ". In his new logic, it will fill html_css_files automatically by checking the existence of python module: sphinx_rtd_theme. While in our previous test, we didn't install it properly. Sorry about this false alarm.

Thanks again for all your contributions to Kernel Sphinx Doc maintenance. It is really helpful for us to learn kernel things.

commit fca7216bf53e7f1f4a8dba6af386d6faa7699fd6
Author: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date:   Tue Dec 7 10:52:59 2021 +0100

    docs: allow selecting a Sphinx theme

    Instead of having RTD as an almost mandatory theme, allow the
    user to select other themes via DOCS_THEME environment var.

    There's a catch, though: as the current theme override logic is
    dependent of the RTD theme, we need to move the code which
    adds the CSS overrides to be inside the RTD theme logic.

    Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
    Link: https://lore.kernel.org/r/bd20adabfd428fd3cd0e69c2cf146aa354932936.1638870323.git.mchehab+huawei@kernel.org
    Signed-off-by: Jonathan Corbet <corbet@lwn.net>

commit d69dab7de208748ddf79143b39d98db55eee9b4a
Author: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date:   Sat Nov 27 10:14:49 2021 +0100

    docs: conf.py: fix support for Readthedocs v 1.0.0

    As described at:
            https://stackoverflow.com/questions/23211695/modifying-content-width-of-the-sphinx-theme-read-the-docs

    since Sphinx 1.8, the standard way to setup a custom theme is
    to use html_css_files. While using html_context is OK with RTD
    0.5.2, it doesn't work with 1.0.0, causing the theme to not load,
    producing a very weird html.

    Tested with:
            - Sphinx 1.7.9 + sphinx-rtd-theme 0.5.2
            - Sphinx 2.4.4 + sphinx-rtd-theme 0.5.2
            - Sphinx 2.4.4 + sphinx-rtd-theme 1.0.0
            - Sphinx 4.3.0 + sphinx-rtd-theme 1.0.0

    Reported-by: Hans Verkuil <hverkuil@xs4all.nl>
    Tested-by: Hans Verkuil <hverkuil@xs4all.nl>
    Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
    Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
    Tested-by: Akira Yokosawa <akiyks@gmail.com>
    Link: https://lore.kernel.org/r/80009f0d17ea0840d81e7e16fff6e7677919fdfc.1638004294.git.mchehab+huawei@kernel.org
    Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Best Regards!
Ming Wen (闻明)
SDK Team | Ambarella Shanghai


-----Original Message-----
From: Jonathan Corbet <corbet@lwn.net> 
Sent: Thursday, June 5, 2025 4:54 AM
To: Ming Wen <mwen@ambarella.com>; Rongrong Cao <rrcao@ambarella.com>; linux-doc@vger.kernel.org
Cc: mchehab@kernel.org; Long Li <longli@ambarella.com>; Jian Tang <jtang@ambarella.com>; Zhao-Yang Chen <zychen@ambarella.com>
Subject: RE: [EXT] Re: [Kernel 5.15/Kernle 6.1] About Sphinx Doc.

Ming Wen <mwen@ambarella.com> writes:

> Thanks for the update. Good to know!

> As the next, Jon may help to check a bit why this changelist is missed 
> to be merged into LTS Kernel 5.15 and even LTS Kernel 6.1. It should 
> definitely be needed.😊

So I have *finally* had a chance to take a look at this.  For 5.15, I can certainly ask that commit d69dab7de208 be backported (I'll note that anybody else can do that too).  BUT: that commit was applied to 5.16, so if there are problems with 6.1, they lie elsewhere.  That makes me suspect that this commit isn't the one we're looking for?

jon

**********************************************************************
This email and attachments contain Ambarella Proprietary and/or Confidential Information and is intended solely for the use of the individual(s) to whom it is addressed. Any unauthorized review, use, disclosure, distribute, copy, or print is prohibited. If you are not an intended recipient, please contact the sender by reply email and destroy all copies of the original message. Thank you.