Skip to contentSkip to conversation

Error at www.kernel.org/doc/html/next/ since next-20250610

DISCUSSION Akira Yokosawa 5 participants 7 messages Jun 16, 2025 – Jun 19, 2025 Documentation

lore
Share & tools
lore
#0 lore raw

Hi Konstantin,

As you might well be aware of, latest successful documentation build against linux-next at https://www.kernel.org/doc/html/next/ was that of next-20250606.

I managed to reproduce the build error using debian bookworm's distro packages which can be close enough to Sphinx 5.3.0 used there.

This is the error I got from "make htmldocs":

----------------------------------------------------------------
Extension error (automarkup):
Handler <function auto_markup at 0x796307745bc0> for event 'doctree-resolved' threw an exception (exception: argument for warn() given by name ('stacklevel') and position (3))
----------------------------------------------------------------

Bisection points to commit d6d1df92c25f ("docs: automarkup: Mark up undocumented entities too") queued in Jon's docs-next branch.

Reverting it resolves the error, but honestly speaking, I don't have any plausible theory on how that change could cause such an issue.

Actually, when I install Sphinx 5.3.0 by using venv and saying

pip install "Sphinx<6.0" pyyaml

on Ubuntu 24.04 today, said error doesn't reproduce.

I'm not sure but there might have been some minor incompatibility between past versions of dependencies.

I'd rather upgrade Sphinx to 8.2.3 (latest).

Konstantin, could you try it?

Thanks, Akira

#1 lore raw

Em Mon, 16 Jun 2025 20:18:22 +0900
Akira Yokosawa <[email protected]> escreveu:

Quoted 8 lines

Hi Konstantin,

As you might well be aware of, latest successful documentation build against linux-next at https://www.kernel.org/doc/html/next/ was that of next-20250606.

I managed to reproduce the build error using debian bookworm's distro packages which can be close enough to Sphinx 5.3.0 used there.

Quoted 6 lines

This is the error I got from "make htmldocs":

----------------------------------------------------------------
Extension error (automarkup):
Handler <function auto_markup at 0x796307745bc0> for event 'doctree-resolved' threw an exception (exception: argument for warn() given by name ('stacklevel') and position (3))
----------------------------------------------------------------

Sphinx crashes generally generate a python dump. Maybe you could take a look on it.

Quoted 11 lines

Bisection points to commit d6d1df92c25f ("docs: automarkup: Mark up undocumented entities too") queued in Jon's docs-next branch.

Reverting it resolves the error, but honestly speaking, I don't have any plausible theory on how that change could cause such an issue.

Actually, when I install Sphinx 5.3.0 by using venv and saying

pip install "Sphinx<6.0" pyyaml

on Ubuntu 24.04 today, said error doesn't reproduce.

Perhaps it is related to docutils version.

Assuming that it doesn't work with certain versions of sphinx or docutils, instead of reverting the entire patch, IMO the best would be to add a check for Sphinx version, disabling the broken refs only for too old versions.

Quoted 8 lines

I'm not sure but there might have been some minor incompatibility between past versions of dependencies.

I'd rather upgrade Sphinx to 8.2.3 (latest).

Konstantin, could you try it?

Thanks, Akira

Regards

Thanks,
Mauro

#2 lore raw

Hi Mauro,

Quoted 2 lines · Mauro Carvalho Chehab

Em Mon, 16 Jun 2025 20:18:22 +0900
Akira Yokosawa <[email protected]> escreveu:

[...]

Quoted 11 lines
Quoted 9 lines

I managed to reproduce the build error using debian bookworm's distro packages which can be close enough to Sphinx 5.3.0 used there.

This is the error I got from "make htmldocs":

----------------------------------------------------------------
Extension error (automarkup):
Handler <function auto_markup at 0x796307745bc0> for event 'doctree-resolved' threw an exception (exception: argument for warn() given by name ('stacklevel') and position (3))
----------------------------------------------------------------

Perhaps it is related to docutils version.

Looks like you are right.

debian:12 (Sphinx 5.3.0) and mageia:9 (Sphinx 6.1.3) are distro releases whose docutils is 0.19. They both show the same symptom.

Furthermore, if I install Sphinx by using venv and saying:

    pip install "docutils==0.19" Sphinx pyyaml

, I have Sphinx 7.3.6 and it shows the same symptom.

So you need to say "docutils!=0.19" when you install specific versions of Sphinx.

Quoted 6 lines

Assuming that it doesn't work with certain versions of sphinx or docutils, instead of reverting the entire patch, IMO the best would be to add a check for Sphinx version, disabling the broken refs only for too old versions.

Can you do so against docutils 0.19 only?

Thanks, Akira

#3 lore raw

Em Thu, 19 Jun 2025 11:22:19 +0900
Akira Yokosawa <[email protected]> escreveu:

Quoted 34 lines

Hi Mauro,

Quoted 2 lines · Mauro Carvalho Chehab

Em Mon, 16 Jun 2025 20:18:22 +0900
Akira Yokosawa <[email protected]> escreveu:

[...]

Quoted 11 lines
Quoted 9 lines

I managed to reproduce the build error using debian bookworm's distro packages which can be close enough to Sphinx 5.3.0 used there.

This is the error I got from "make htmldocs":

----------------------------------------------------------------
Extension error (automarkup):
Handler <function auto_markup at 0x796307745bc0> for event 'doctree-resolved' threw an exception (exception: argument for warn() given by name ('stacklevel') and position (3))
----------------------------------------------------------------

Perhaps it is related to docutils version.

Looks like you are right.

debian:12 (Sphinx 5.3.0) and mageia:9 (Sphinx 6.1.3) are distro releases whose docutils is 0.19. They both show the same symptom.

Furthermore, if I install Sphinx by using venv and saying:

    pip install "docutils==0.19" Sphinx pyyaml

, I have Sphinx 7.3.6 and it shows the same symptom.

So you need to say "docutils!=0.19" when you install specific versions of Sphinx.

Quoted 1 line
Quoted 7 lines
Quoted 5 lines

Assuming that it doesn't work with certain versions of sphinx or docutils, instead of reverting the entire patch, IMO the best would be to add a check for Sphinx version, disabling the broken refs only for too old versions.

Can you do so against docutils 0.19 only?

If we're willing to do that, IMO we need to do a more generic solution that will compare both versions and warn if incompatibilities are detected.

Something like the enclosed patch (it is against my latest conf.py patch).

Thanks,
Mauro

---

[PATCH] docs: conf.py: Check Sphinx and docutils version

As reported by Akira, there are incompatibility issues with Sphinx and docutils.

I manually checked that before docutils 0.17.1, yaml generation doesn't work properly. Akira checked that 0.19 is problematic too.

After check Sphinx release notes, it seems that the versions that are supposed to cope well together are:

	========  ============  ============
	Sphinx    Min Docutils  Max Docutils
	Version   Version       Version
	--------  ------------  ------------
	< 4.0.0	  0.17.1        0.17.1
	< 6.0.0	  0.17.1        0.18.1
	< 7.0.0   0.18.0        0.18.1
	>= 7.0.0  0.20.0        0.21.2
	========  ============  ============

Add a logic inside conf.py to check the above, emitting warnings if the docutils version don't match what is known to be supported.

Documentation/conf.py +30 -3
index 5eddf5885f77..6047ec85add1 100644
@@ -9,7 +9,11 @@ import os
 import shutil
 import sys
 
+import docutils
 import sphinx
+from sphinx.util import logging
+
+logger = logging.getLogger(__name__)
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -21,11 +25,34 @@ from load_config import loadConfig               # pylint: disable=C0413,E0401
 # Minimal supported version
 needs_sphinx = "3.4.3"
 
-# Get Sphinx version
-major, minor, patch = sphinx.version_info[:3]          # pylint: disable=I1101
+# Get Sphinx and docutils versions
+sphinx_ver = sphinx.version_info[:3]          # pylint: disable=I1101
+docutils_ver = docutils.__version_info__[:3]
+
+#
+if sphinx_ver < (4, 0, 0):
+    min_docutils = (0, 16, 0)
+    max_docutils = (0, 17, 1)
+elif sphinx_ver < (6, 0, 0):
+    min_docutils = (0, 17, 0)
+    max_docutils = (0, 18, 1)
+elif sphinx_ver < (7, 0, 0):
+    min_docutils = (0, 18, 0)
+    max_docutils = (0, 18, 1)
+else:
+    min_docutils = (0, 20, 0)
+    max_docutils = (0, 21, 2)
+
+sphinx_ver_str = ".".join([str(x) for x in sphinx_ver])
+docutils_ver_str = ".".join([str(x) for x in docutils_ver])
+
+if docutils_ver < min_docutils:
+    logger.warning(f"Docutils {docutils_ver_str} is too old for Sphinx {sphinx_ver_str}. Doc generation may fail")
+elif docutils_ver > max_docutils:
+    logger.warning(f"Docutils {docutils_ver_str} could be too new for Sphinx {sphinx_ver_str}. Doc generation may fail")
 
 # Include_patterns were added on Sphinx 5.1
-if (major < 5) or (major == 5 and minor < 1):
+if sphinx_ver < (5, 1, 0):
     has_include_patterns = False
 else:
     has_include_patterns = True
reviewer
#4 lore raw
Quoted 79 lines · Mauro Carvalho Chehab

Em Thu, 19 Jun 2025 11:22:19 +0900
Akira Yokosawa <[email protected]> escreveu:

Quoted 2 lines

Can you do so against docutils 0.19 only?

If we're willing to do that, IMO we need to do a more generic solution that will compare both versions and warn if incompatibilities are detected.

Something like the enclosed patch (it is against my latest conf.py patch).

Thanks,
Mauro

---

[PATCH] docs: conf.py: Check Sphinx and docutils version

As reported by Akira, there are incompatibility issues with Sphinx and docutils.

I manually checked that before docutils 0.17.1, yaml generation doesn't work properly. Akira checked that 0.19 is problematic too.

After check Sphinx release notes, it seems that the versions that are supposed to cope well together are:

	========  ============  ============
	Sphinx    Min Docutils  Max Docutils
	Version   Version       Version
	--------  ------------  ------------
	< 4.0.0	  0.17.1        0.17.1
	< 6.0.0	  0.17.1        0.18.1
	< 7.0.0   0.18.0        0.18.1
	>= 7.0.0  0.20.0        0.21.2
	========  ============  ============

Add a logic inside conf.py to check the above, emitting warnings if the docutils version don't match what is known to be supported.

Documentation/conf.py +14 -2
index 5eddf5885f77..6047ec85add1 100644
@@ -9,7 +9,11 @@ import os
 import shutil
 import sys
 
+import docutils
 import sphinx
+from sphinx.util import logging
+
+logger = logging.getLogger(__name__)
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -21,11 +25,34 @@ from load_config import loadConfig               # pylint: disable=C0413,E0401
 # Minimal supported version
 needs_sphinx = "3.4.3"
 
-# Get Sphinx version
-major, minor, patch = sphinx.version_info[:3]          # pylint: disable=I1101
+# Get Sphinx and docutils versions
+sphinx_ver = sphinx.version_info[:3]          # pylint: disable=I1101
+docutils_ver = docutils.__version_info__[:3]
+
+#
+if sphinx_ver < (4, 0, 0):
+    min_docutils = (0, 16, 0)
+    max_docutils = (0, 17, 1)
+elif sphinx_ver < (6, 0, 0):
+    min_docutils = (0, 17, 0)

Documentation/conf.py from load_config import loadConfig # pylint: disable=C0413,E0401 · line 47

Quoted 10 lines
Documentation/conf.py +10 -0
+    max_docutils = (0, 18, 1)
+elif sphinx_ver < (7, 0, 0):
+    min_docutils = (0, 18, 0)
+    max_docutils = (0, 18, 1)
+else:
+    min_docutils = (0, 20, 0)
+    max_docutils = (0, 21, 2)
+
+sphinx_ver_str = ".".join([str(x) for x in sphinx_ver])
+docutils_ver_str = ".".join([str(x) for x in docutils_ver])

That ".". (2 times) is ugly. ;) (needs spaces added IMO)
Is that compliant with PEP8?
I can't see that PEP8 addresses usage of . directly. For some binary operators:
Always surround these binary operators with a single space on either side: assignment (=), augmented assignment (+=, -= etc.), comparisons (==, <, >, !=, <=, >=, in, not in, is, is not), Booleans (and, or, not).
[https://peps.python.org/pep-0008/#whitespace-in-expressions-and-statements]

Thanks.

Quoted 14 lines
Documentation/conf.py +6 -1
+
+if docutils_ver < min_docutils:
+    logger.warning(f"Docutils {docutils_ver_str} is too old for Sphinx {sphinx_ver_str}. Doc generation may fail")
+elif docutils_ver > max_docutils:
+    logger.warning(f"Docutils {docutils_ver_str} could be too new for Sphinx {sphinx_ver_str}. Doc generation may fail")
 
 # Include_patterns were added on Sphinx 5.1
-if (major < 5) or (major == 5 and minor < 1):
+if sphinx_ver < (5, 1, 0):
     has_include_patterns = False
 else:
     has_include_patterns = True
Signature · 1 line
~Randy
#5 lore raw
In reply to Akira Yokosawa
Quoted 6 lines · Akira Yokosawa

I'm not sure but there might have been some minor incompatibility between past versions of dependencies.

I'd rather upgrade Sphinx to 8.2.3 (latest).

Konstantin, could you try it?

Looks like 8.2.3 requires python-3.11, which I don't have readily available on the system that builds the documentation. However, upgrading to 7.4 also fixed the problem, so the latest next tree is now built and should be propagating shortly.

Thanks,
-K

maintainer
#6 lore raw
Quoted 4 lines · Konstantin Ryabitsev
Quoted 3 lines · Akira Yokosawa

I'm not sure but there might have been some minor incompatibility between past versions of dependencies.

Quoted 8 lines
Quoted 3 lines

I'd rather upgrade Sphinx to 8.2.3 (latest).

Konstantin, could you try it?

Looks like 8.2.3 requires python-3.11, which I don't have readily available on the system that builds the documentation. However, upgrading to 7.4 also fixed the problem, so the latest next tree is now built and should be propagating shortly.

[Catching up after some much-needed time in the wilderness...]

Konstantin, is there any easy way to get a notification when the build there fails? I was entirely unaware of the problem, needless to say.

Once I've dug out a little further, I'll try to figure out why my change makes things explode. It really shouldn't...so it should be possible to find a way to work around the problem and avoid putting in version requirements (and tests) that we haven't needed so far.

Thanks,

jon