On Thu, 06 Oct 2016, Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxx> wrote: > Em Thu, 06 Oct 2016 11:42:14 +0300 > Jani Nikula <jani.nikula@xxxxxxxxx> escreveu: > Just curious here: what use case do you see by building the Kernel > documentation without the Kernel tree? Not without the kernel tree, but without the kernel build system. If sphinx-build works directly, https://readthedocs.org/ just works when you point it at a kernel git repo and the conf.py inside it. It would be important to get Sphinx working over at https://www.kernel.org/doc/htmldocs/ (which still looks kind of sad) but in the mean time we could have had that at https://readthedocs.org/. If it weren't for parse-headers.pl and the build hacks around it. At least there's one at https://01.org/linuxgraphics/gfx-docs/drm/ now. >> However, I would have much preferred the approach I proposed months ago, >> having the extension itself do specifically what parse-headers.pl does >> now. While it may seem generic on the surface, I don't think it's a >> clean or a secure approach to allow running of arbitrary scripts from >> PATH while building documentation. It's certainly not an approach that >> should be encouraged. > > Sorry, but I disagree. The security threat of having a random command > doing something wrong is the same as we already have with the Kernel > Makefiles, as they can also run a random command. All it is needed > is to add this to a Makefile: My intention was to emphasize the importance of the clarity of the documentation build, and not get hung up on the security aspect. This is connected to the above: keeping documentation buildable with sphinx-build directly will force you to avoid the Makefile hacks. > IMO, a generic solution is a way better, as it sounds easier to > maintain. We've seen what happens when we make it easy to add random scripts to build documentation. We've worked hard to get rid of that. In my books, one of the bigger points in favor of Sphinx over AsciiDoc(tor) was getting rid of all the hacks required in the build. Things that broke in subtle ways. I think having people write Sphinx extensions for the special needs have a better chance of solving the problems in more generic ways than writing scripts for each specific need. Ideally, we can push those extensions to upstream Sphinx, but at least make them easily usable across the kernel documentation. Case in point, parse-headers.pl was added for a specific need of media documentation, and for the life of me I can't figure out by reading the script what good, if any, it would be for gpu documentation. I call *that* unmaintainable. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
