mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Linux Doc Mailing List <linux-doc@vger.kernel.org>,
	Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
	"Akira Yokosawa" <akiyks@gmail.com>,
	"Mauro Carvalho Chehab" <mchehab+huawei@kernel.org>,
	linux-kernel@vger.kernel.org
Subject: [PATCH v2 15/15] docs: conf.py: Check Sphinx and docutils version
Date: Sat, 21 Jun 2025 21:55:54 +0200	[thread overview]
Message-ID: <52e195e9660e2086bc90da977e7d4e8b9efe53f5.1750535171.git.mchehab+huawei@kernel.org> (raw)
In-Reply-To: <cover.1750535171.git.mchehab+huawei@kernel.org>

As reported by Akira, there were incompatibility issues with
Sphinx and docutils with docutils 0.19. There's already
a fix for it, but, as there are incompatibility issues with
different versions, better to add a check to verify if the
combination is supported/tested.

After check Sphinx release notes, it seems that the
version compatibility is given by:

        =======  ============   ============
        Sphinx   Min Docutils   Max Docutils
        Version  Version        Version
        -------  ------------   ------------
        3.4.3    >= 0.12.0      < 0.18.0
        4.0.0    >= 0.12.0      < 0.19.0
        6.0.0    >= 0.18.0      < 0.20.0
        7.0.0    >= 0.18.1      < 0.21.0
        7.2.0    >= 0.18.1      < 0.20.0
        7.4.0    >= 0.18.1      < 0.21.0
        8.0.0    >= 0.20.0      < 0.22.0
        8.2.3    >= 0.20.0      < 0.22.0
        =======  ============   ============

For now, add a logic inside conf.py to check the above
compatibility list, emitting warnings if the docutils
version doesn't match it.

This way, when we discover incompatibility issues, we
can easily adjust the table.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/conf.py | 70 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 67 insertions(+), 3 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index e4dde5aa4559..945198bd1f1f 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -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,71 @@ 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]
+
+sphinx_ver_str = ".".join([str(x) for x in sphinx_ver])
+docutils_ver_str = ".".join([str(x) for x in docutils_ver])
+
+# Docutils min/max versions.
+# The dockutils version check logic is done with:
+#     ver >= min and ver < max
+SPHINX_DOCUTILS_VERS = {
+    (3, 4, 3): {
+        "min": (0, 12, 0),
+        "max": (0, 18, 0)
+    },
+    (4, 0, 0): {
+        "min": (0, 12, 0),
+        "max": (0, 19, 0)
+    },
+    (6, 0, 0): {
+        "min": (0, 18, 0),
+        "max": (0, 20, 0)
+    },
+    (7, 0, 0): {
+        "min": (0, 18, 1),
+        "max": (0, 21, 0)
+    },
+    (7, 2, 0): {
+        "min": (0, 18, 1),
+        "max": (0, 20, 0)
+    },
+    (7, 4, 0): {
+        "min": (0, 18, 1),
+        "max": (0, 21, 0)
+    },
+    (8, 0, 0): {
+        "min": (0, 20, 0),
+        "max": (0, 22, 0)
+    },
+    (8, 2, 3): {
+        "min": (0, 20, 0),
+        "max": (0, 22, 0)
+    },
+}
+
+du_min = None
+du_max = None
+for sp_ver, doc_vers in SPHINX_DOCUTILS_VERS.items():
+    if sp_ver > sphinx_ver:
+        break
+
+    du_min = doc_vers.get("min")
+    du_max = doc_vers.get("max")
+
+if sphinx_ver > sorted(SPHINX_DOCUTILS_VERS.keys())[-1]:
+    logger.warning(f"Sphinx version {sphinx_ver_str} is too new and not tested. Doc generation may fail")
+elif not du_min or not du_max:
+    logger.warning(f"Sphinx version {sphinx_ver_str} is not tested. Doc generation may fail")
+elif docutils_ver < du_min:
+    logger.warning(f"Docutils {docutils_ver_str} is too old for Sphinx {sphinx_ver_str}. Doc generation may fail")
+elif docutils_ver >= du_max:
+    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
-- 
2.49.0


  parent reply	other threads:[~2025-06-21 19:56 UTC|newest]

Thread overview: 18+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2025-06-21 19:55 [PATCH v2 00/15] Some improvements and fixes for the doc build system Mauro Carvalho Chehab
2025-06-21 19:55 ` [PATCH v2 01/15] docs: conf.py: properly handle include and exclude patterns Mauro Carvalho Chehab
2025-06-21 19:55 ` [PATCH v2 02/15] docs: Makefile: disable check rules on make cleandocs Mauro Carvalho Chehab
2025-06-21 19:55 ` [PATCH v2 03/15] scripts: scripts/test_doc_build.py: add script to test doc build Mauro Carvalho Chehab
2025-06-21 19:55 ` [PATCH v2 04/15] scripts: test_doc_build.py: make capture assynchronous Mauro Carvalho Chehab
2025-06-21 19:55 ` [PATCH v2 05/15] scripts: test_doc_build.py: better control its output Mauro Carvalho Chehab
2025-06-21 19:55 ` [PATCH v2 06/15] scripts: test_doc_build.py: better adjust to python version Mauro Carvalho Chehab
2025-06-21 19:55 ` [PATCH v2 07/15] scripts: test_doc_build.py: improve dependency list Mauro Carvalho Chehab
2025-06-21 19:55 ` [PATCH v2 08/15] scripts: test_doc_build.py: improve cmd.log logic Mauro Carvalho Chehab
2025-06-21 19:55 ` [PATCH v2 09/15] scripts: test_doc_build.py: make the script smarter Mauro Carvalho Chehab
2025-06-21 19:55 ` [PATCH v2 10/15] scripts: sphinx-pre-install: properly handle SPHINXBUILD Mauro Carvalho Chehab
2025-06-21 19:55 ` [PATCH v2 11/15] scripts: sphinx-pre-install: fix release detection for Fedora Mauro Carvalho Chehab
2025-06-21 19:55 ` [PATCH v2 12/15] scripts: test_doc_build.py: regroup and rename arguments Mauro Carvalho Chehab
2025-06-21 19:55 ` [PATCH v2 13/15] docs: sphinx: add a file with the requirements for lowest version Mauro Carvalho Chehab
2025-06-21 19:55 ` [PATCH v2 14/15] docs: conf.py: several coding style fixes Mauro Carvalho Chehab
2025-06-21 19:55 ` Mauro Carvalho Chehab [this message]
2025-06-21 20:09 ` [PATCH v2 00/15] Some improvements and fixes for the doc build system Jonathan Corbet
2025-06-22  5:48   ` Mauro Carvalho Chehab

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=52e195e9660e2086bc90da977e7d4e8b9efe53f5.1750535171.git.mchehab+huawei@kernel.org \
    --to=mchehab+huawei@kernel.org \
    --cc=akiyks@gmail.com \
    --cc=corbet@lwn.net \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox

all inboxes | Powered by JetHome®