Re: parts of media docs sphinx re-building every time?

[Jani Nikula <jani.nikula@intel.com>]

On Mon, 08 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> Hi Jani,
>
> Am 08.08.2016 um 17:37 schrieb Jani Nikula <jani.nikula@intel.com>:
>
>> 
>> 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