Re: Kernel docs: muddying the waters a bit

[Mauro Carvalho Chehab]

Em Wed, 4 May 2016 08:57:13 -0600
Jonathan Corbet <corbet@xxxxxxx> escreveu:

> On Wed, 4 May 2016 16:18:27 +0200
> Daniel Vetter <daniel.vetter@xxxxxxxx> wrote:
> 
> > > I'd really like to converge on the markup question, so that we can start
> > > using all the cool stuff with impunity in gpu documentations.    
> > 
> > Aside: If we decide this now I could send in a pull request for the
> > rst/sphinx kernel-doc support still for 4.7 (based upon the minimal
> > markdown/asciidoc code I still have). That would be really awesome ...  
> 
> Sorry for my relative absence...I'm still busy dealing with bureaucracy
> an ocean away from home.  I hope to begin emerging from this mess in the
> near future.
> 
> So ... there's the code you have, the work I (+Jani) did, and the work
> Markus has done.  Which would you have me push into 4.7?

IMHO, Markus approach is the one that is providing a better result,
as it added support for missing features that we require for the
media DocBook.

Still, it seems premature to merge it for 4.7.

Markus is getting real progress on converting the media docs to work
with Sphynx, but there are still troubles when the table is big, as,
currently, it is truncating everything that passes the right margin
on some tables.

So, IMHO, the next action item would be to be sure that big tables 
will not be truncated. Assuming that he can fix that in time, we
can merge it for 4.8, and then start porting the documentation to
use it.

Btw, converting the DocBook/media Makefile will require an extra
step, as part of the documentation is generated via scripts (some
C file examples, and include/uapi headers). Those scripts also
warrant that (almost) every API at include/uapi is synchronized
with the DocBook. I use this on my patch review process, in order
to reject patches that don't add the proper documentation updates.

Thanks,
Mauro