On Sat, 04 Jun 2022, Akira Yokosawa <akiyks@xxxxxxxxx> wrote: > [+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. That doesn't change my opinion that it would be best avoided! ;) BR, Jani. > > 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 -- Jani Nikula, Intel Open Source Graphics Center
