On Mon, 08 Aug 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote: > Hi Jani, > > Am 08.08.2016 um 17:37 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>: > >> >> Hi Mauro & co - >> >> I just noticed running 'make htmldocs' rebuilds parts of media docs >> every time on repeated runs. This shouldn't happen. Please investigate. >> >> I wonder if it's related to Documentation/media/Makefile... which I have >> to say I am not impressed by. I was really hoping we could build all the >> documentation by standalone sphinx-build invocation too, relying only on >> the conf.py so that e.g. Read the Docs can build the docs. Part of that >> motivation was to keep the build clean in makefiles, and handing the >> dependency tracking completely to Sphinx. >> >> I believe what's in Documentation/media/Makefile, >> Documentation/sphinx/parse-headers.pl, and >> Documentation/sphinx/kernel_include.py could be replaced by a Sphinx >> extension looking at the sources directly. > > Yes, parse-headers.pl, kernel_include.py and media/Makefile are needed > for one feature ... not very straight forward. > > If it makes sense to migrate the perl scripts functionality to a > Sphinx extension, may I can help ... depends on what Mauro thinks. > > BTW: parse-headers.pl is not the only perl script I like to migrate to py ;) If I understand the need of all of this right, I think the cleanest and fastest short term measure would be to make the kernel-include directive extension do the same thing as the kernel-doc directive does: call the perl script from the directive. This lets you get rid of Documentation/media/Makefile and you don't have to copy-paste all of Include.run method into kernel_include.py. You can also get rid of specifying environment variables in rst files and parsing them in the extension. We can get rid of the problematic intermediate rst files. This design has been proven with the kernel-doc extension and script already. It's much simpler. 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
