Em Fri, 03 Jun 2022 22:05:20 +0300 Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> escreveu: > On Sat, 04 Jun 2022, Akira Yokosawa <akiyks@xxxxxxxxx> wrote: > > [+Cc: Mauro] Thanks! > > > > 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! ;) Em Fri, 3 Jun 2022 15:27:18 +0000 Adam Turner <aaturnerpython@xxxxxxxxxxx> escreveu: > I'm referring to removing support for the "c_allow_pre_v3", > "c_warn_on_allowed_pre_v3", configuration options [1]_, and the > associated support for still parsing the pre v3 syntax in the C > domain [2]_. This means that pre v3 syntax in reStructuredText files > would not work with Sphinx 6 onwards. If all that it is scheduled for Sphinx 6 is the removal of the old C domain, this shouldn't be a problem. The kernel-doc has long gone support to output tags with both pre and post v3 syntaxes. We also changed the automarkup plugin to allow using v3 C domain tags when compiling against pre-v3. Tests required, of course. - >From my side, there are two points to consider when changing the minimal release: - Supporting a version that can build docs 2x faster sounds very interesting; - it would also be interesting to support the native Sphinx version that comes with the latest LTS releases, As I suspect that bots may benefit from a long-term distros, and use the distro-provided signed packages on servers. Looking at LTS, what we have is: - RHEL 9.0/CentOS 9.0: https://centos.pkgs.org/9-stream/centos-crb-x86_64/python3-sphinx-latex-3.4.3-7.el9.noarch.rpm.html Sphinx 3.4.3 - Debian 11: Sphinx 3.4.3 https://packages.debian.org/bullseye/python3-sphinx - Suse 15 SP4: https://scc.suse.com/packages?name=SUSE%20Linux%20Enterprise%20Server&version=15.4&arch=x86_64&query=python3-sphinx&module= Have have both Sphinx 4.2.0 and Sphinx 2.3.1 From LTS perspective, it sounds doable to setup the minimal version to 3.4, but we would need to adjust the scripts to select a different package on Suse, as calling: ./scripts/sphinx-pre-install --no-virtualenv Would recommend installing python3-sphinx package there, meaning Sphinx 2.3.1. So, IMO, we have a couple of alternatives: 1. Change minimal requirement to 2.3: - No changes required at sphinx-pre-install's logic; - all latest LTS will be supported; - pdf will still require a newer version than 2.3. - allow "fast builds" with Sphinx < 3; 2. Change minimal requirement to 2.4: - no need to check for an specific version for PDF; - allow "fast builds" using Sphinx < 3; - Changes needed at sphinx-pre-install on Suse logic; 3. Change minimal requirement to 3.4: - We can drop backward-compatible logic from kernel-doc and automarkup; - all latest LTS will be supported; - Changes needed at sphinx-pre-install on Suse logic; - No "fast build" suing Sphinx < 3. On a side note, while Kernel documentation builds with 3.0, it is not really properly supported, as there are troubles on C domain there (lots of warnings and broken cross references are generated there). So, I would avoid setting the minimal requirement to 3.0. Regards, Mauro
