On Mon, May 25, 2020 at 03:08:40PM +0300, Jani Nikula wrote: > >> It is wasting time ;) .. The Makefile targets do build > >> intermedaiate > >> files using perl and other scripts, this will never work on RTD. > > > > Okay, I'd suspected as much after poking around things a bit. Another > > possibility would be to have a separate repository where we commit the > > doc tree (after it's massaged into the "ready to be built with sphinx" > > condition). We could run this automatically on our end on each mainline > > release, but it's certainly not a necessity. > > FWIW, when I was developing the Sphinx documentation build for the > kernel, I carefully tried to ensure everything would build directly, and > consequently also at readthedocs.org. I kept testing it at RTD too. > > For this reason I kept resisting the addition of any Makefile trickery, > and insisting we should do everything through Sphinx. This would have > meant writing Sphinx extensions for all the hacks people wanted to > add. But it would also have lead to a self-contained system with fewer > moving parts, which I thought was worth pursuing. And, obviously, would > have made it possible to host the documentation at RTD. > > I failed. Stuff just keeps piling up in the Makefiles. Well, if someone gives me a way to create a sphinx-buildable tree out of the contents of Documentation/*, I would be happy to maintain it and host on RTD. I think there is benefit to have a repository of just docs, even if it is secondary to the main repo and is auto-committed there on each mainline release. > In fairness, the kernel documentation build was growing too big even for > RTD. It kept timing out and/or consuming too much resources. I believe > that would have been possible to sort out with the RTD maintainers, > given the possibility to host kernel documentation, but there was no > point in pursuing this since the docs wouldn't build directly anyway. I've already negotiated with RTD.org to significantly extend the build time, so that's not a concern. -K
