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. > > It's hard enough to get people to write documentation. It's also hard > enough to get them to test building their documentation before > submitting it. I think there is a lot of value in being able to build > the documentation for the subtree you're contributing to, and be able to > have some expectation that it builds cleanly. Let's not make it more > difficult for the people who are actually adding substantive > documentation. 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. 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. For the bigger problem, the right answer is to start using intersphinx. I guess I need to get serious about playing with that. Thanks, jon
