Am 01.07.2016 um 11:38 schrieb Mauro Carvalho Chehab <mche...@osg.samsung.com>:
> 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
