[+Cc: Mauro] 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. Its help text says: > Output format modifiers > reStructuredText only > -sphinx-version VERSION > Use the ReST C domain dialect compatible with a specific Sphinx > Version. > > If not specified, kernel-doc will auto-detect using the > sphinx-build version found on PATH. So it looks to me like it is already compatible with Sphinx 3.1 and later. > > I don't want to be in the position of knowingly breaking the > documentation tooling for the kernel. A strawman of a compromise > would be for us (Sphinx) to delay the removal to Sphinx 7.0, and the > kernel to increase the minimum to Sphinx 3.1 (required for > ".. c:namespace::"). Yes, ".. c:namespace::" is actively used in userspace-api documentation. FYI, see a recent reply from Mauro WRT support of kernel documentation with different versions of Sphinx at: https://lore.kernel.org/linux-doc/20220521114629.6ee9fc06@xxxxxxxx/ Thanks, Akira > That would enable the kernel to gradually update > the syntax over a longer period, as I believe you won't be able to > use the v3 syntax currently. > > Equally, Jonathan said he was hesitant to increase the minimum to > Sphinx 3, so perhaps that wouldn't work. > > A
