Re: [PATCH] doc: flat-table directive

[Mauro Carvalho Chehab]

Em Fri, 1 Jul 2016 14:18:34 +0200
Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu:

> Am 01.07.2016 um 11:38 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxx>:
> 
> 
> > Btw, yesterday, I tried to add references to a C code, at video.rst,
> > just like we did with DocBook:
> > 
> > .. code-block:: c
> >   :caption: Example 2: Switching to the first video input
> > 
> >   int index;
> > 
> >   index = 0;
> > 
> >   if (-1 == ioctl(fd, :ref:`VIDIOC_S_INPUT <vidioc-s-input>`, &index)) {
> >       perror("VIDIOC_S_INPUT");
> >       exit(EXIT_FAILURE);
> >   }
> > 
> > But Sphinx didn't allow doing it. I was unable to find any syntax
> > on it that would make Sphinx use a monospaced font but still parse
> > the references at the code. While for those small examples this would
> > be ok, This is something that we do want for the header files that
> > we put at V4L and DVB annexes. For DocBook, we do a lot of things like
> > this at the DocBook/media/Makefile:
> > 	sed -e "s/\(enum *\)v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1<link linkend=\"\2\">v4l2_mpeg_cx2341x_video_\2<\/link>/g" videodev2.h  
> 
> In Sphinx, the code-block directive is a literal block, no refs or markup
> will be interpreted. This is different to what you know from DocBook.
> I will look for a solution, that matches your requirement.

Ok, thanks!

> > The actual code is a way more complex, but basically the idea is that
> > it escapes anything that DocBook might interpret as a command, and adds
> > <link> tags for every enum, typedef, ioctl, struct, syscall and define
> > it founds at the header files. the xmllint will produce errors when
> > links are not solved, and we'll be able to detect that the API is not
> > fully documented.  
> 
> OK, checking dead internal links might be one requirement more. Normally 
> sphinx reports internal refs which are broken with a WARNING, but I have to
> analyze what xmllint checks and how we could realize something similar
> in sphinx / or if it is enough what sphinx reports. 

An option at Sphinx to handle warnings as errors would be useful. Yet,
it is not hard to modify my build scripts to handle WARNING as errors.

> 
> > We need to do a similar process with Sphinx. A side effect is that, if
> > someone looks at the header files in the anexes, it can click on any
> > symbol at the API and see the full documentation.  
> 
> Yes, altogether, it seems to be a nice feature, I have to think about. But
> I will point it in a separate thread.

Ok, thanks!

> > Btw, in the case of the above example, I had to manually number it as
> > "Example 2", because I was unable to find a way with Sphinx to auto
> > numerate code-block captions. This is also something we want to fix,
> > as it is very hard to manually number things on a 600+ page document.
> >   
> 
> This needs a sphinx extension, I have seen similar solutions for 
> numbering figures on the net ... I will try to find a small solution.

Yeah, we'll need this for figures and tables too.

> But before I will send out some small patches which are needed 
> first (IMHO). E.g. customizing the RTD theme for rendering large 
> tables in HTML well and activation of useful extensions like todolist.
> I have this in my "chaotic bulk" patch :-) ... 

Ah, yes, I noticed that the .. todolist was causing warnings...
I ended by adding a patch removing it internally, as there weren't
anything at the todo block :)

> I will separate it out an send it to Jon one by one.

OK!

Thanks!
Mauro