Re: [PATCH] doc: flat-table directive

[Markus Heiser]

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.

> 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. 

> 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.

> --
> 
> 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.

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 :-) ... I will separate it out
an send it to Jon one by one.

-- Markus --

> Regards,
> Mauro