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

[Mauro Carvalho Chehab <mchehab@infradead.org>]

Em Wed, 10 Aug 2016 10:46:44 +0300
Jani Nikula <jani.nikula@intel.com> escreveu:

> On Mon, 08 Aug 2016, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> > The goal of Documentation/sphinx/parse-headers.pl script is to generate
> > such parsed headers, with the cross-references modified by an exceptions
> > file at Documentation/media/*.h.rst.exceptions.  
> 
> Would you be so kind as to state in a few lines what you want to
> achieve? I can guess based on the current solution, but I'd like to hear
> it from you. Please leave out rants about tools and languages etc. so we
> can focus on the problem statement, and try to figure out the best
> overall solution.

It is basically what's written above: to produce a cross-referenced output
document from a source, were, clicking on the API symbols will navigate to
the place where the symbol was documented.

It should allow to add exceptions, as we don't want to add cross-references
for legacy symbols or helper macros, for example. 

This is a good example on what we want:
	https://linuxtv.org/downloads/v4l-dvb-apis-new/media/uapi/rc/lirc-header.html#lirc-h

The only parts of the header file that will have a different color will be
the symbols defined at the API.

This way, it is easy for us to visually discover what stuff is not yet
documented (like LIRC_MODE2_SPACE - that should be documented - and
_LINUX_LIRC_H macro - that should not be documented).
When something is not cross-referenced there, there's a single place to
look that will explain why this was not documented (at the exceptions file).

The main goal for documentation writers is to use the header
file to identify the documentation gaps. For code developers, the header
file works like an index to the document, where all the API can be seen
altogether, and more details can easily be obtained by clicking at the links.

Regard


Cheers,
Mauro