On 3/13/23 20:37, Jonathan Corbet wrote: > David Vernet <void@xxxxxxxxxxxxx> writes: > >> Sure, but there are practicalities to consider here. It takes O(minutes) >> to do a full docs build, as opposed to O(seconds). I've done reviews of >> docs patches where the engineer tried to build the docs tree, but >> thought it was hung and ended up cancelling it. Full docs builds also >> unfortunately spew quite a few warnings in other subtrees. You have to >> carefully wade through the warnings in those other subtrees to ensure >> you haven't added any new ones. >> I have tried to add CONFIG_COMPILE_TEST + CONFIG_WARN_MISSING_DOCUMENTS + CONFIG_WARN_ABI_ERRORS when performing htmldocs build, but hangs on checking missing documents (even I noticed this behavior when cleandocs). > I get your point, but that is essentially saying that there should be no > linkages between our documentation subtrees, which defeats much of the > purpose of using a system like Sphinx. > I mean external referencing to docs.kernel.org when simple internal linking below should suffice, right? > In this specific case, though, there is a better solution. Text like: > > see the netdev FAQ (Documentation/process/maintainer-netdev.rst) > > will add links in the built docs, and also tells readers of the > plain-text files where they should be looking. Without adding warnings. > OK. In 287f4fa99a5281, Sphinx generates netdev-FAQ crossref as link to `/process/maintainer-netdev.html#netdev-faq`, due to use of external link syntax. Thanks. -- An old man doll... just what I always wanted! - Clara
