Re: [PATCH] doc: flat-table directive

[Mauro Carvalho Chehab]

Em Fri, 01 Jul 2016 10:44:27 +0200
Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu:

> Am 30.06.2016 um 21:44 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxx>:
> 
> > Em Thu, 30 Jun 2016 13:05:11 -0600
> > Jonathan Corbet <corbet@xxxxxxx> escreveu:
> >   
> >> Anyway, I don't want to delay this work, so I have gone ahead and applied
> >> it;   
> > 
> > Got already one issue... Maybe on Jeni's changes to the makefiles...
> > 
> > I want to be able to compile just the book I'm working.  
> 
> This feature does not exists (yet) for the reST content. Jani and I
> discussed it on the ML, but for the start he didn't want to have
> books (aka sphinx sub-projects). Anyway, I don't want to restart
> the discussion again, just the fact for information: no books
> in reST, there is only one HTML site which includes all reST content.
> 
> > Using the usual
> > syntax to build just one book worked: the build from the *.rst files
> > succeeded. Yet, it tried to compile it also as DocBook, causing an
> > error at the end.
> > 
> > See the logs below:
> > 
> > $ make DOCBOOKS=linux_tv htmldocs
> >  SPHINX  htmldocs  
> 
> As far as I know, there is only the one html-target "htmldocs" building
> all HTML from reST & DocBook content. Selecting DocBook-XML books with the
> environment "DOCBOOKS=..." is new for me. Did this feature exists in the 
> past? I tried it with v4.6 but no success.

It exists, and I rely on such feature when merging patches.
Basically, for each patch I merge on my tree, I compile it.
if make returns an error, I play a buzz audio and I reject the
patch. I do the same for documentation: if the patch touches a file
listed at device_drivers.xml, I run this script:

	rm Documentation/DocBook/device-drivers.aux.xml  Documentation/DocBook/device-drivers.xml
	echo "Building device-drivers.xml"
	make DOCBOOKS=device-drivers.xml htmldocs 2>&1
	if [ "$?" != "0" ]; then
		echo -en '\e[0;31m'
		echo -e "***********\n***ERROR***\n***********\n\n"
		echo -en '\e[0;37m'
		play ~/sounds/pipe.wav 2>/dev/null >/dev/null
		exit -1 
	fi

And, if it touches on any file under Documentation/DocBook/media,
I run this script:

	make cleanmediadocs
	make DOCBOOKS=media_api.xml htmldocs 2>&1 | grep -v "element.*: validity error : ID .* already defined"
	echo
	echo "Do some pedantic checks and generate DocBook/media/media_api.html without chunks"
	echo
	xmllint --noent --postvalid "$PWD/Documentation/DocBook/media_api.xml" >/tmp/x.xml 2>/dev/null
	xmllint --noent --postvalid --noout /tmp/x.xml
	xmlto html-nochunks -m ./Documentation/DocBook/stylesheet.xsl -o Documentation/DocBook/media Documentation/DocBook/media_api.xml >/dev/null 2>&1
	if [ "$?" != "0" ]; then
		echo -en '\e[0;31m'
		echo -e "***********\n***ERROR***\n***********\n\n"
		echo -en '\e[0;37m'
		play ~/sounds/pipe.wav 2>/dev/null >/dev/null
		exit -1 
	fi

In the case of the DocBook, as we have all header files using references
to the code (and such references are dynamically created when make htmldocs
run), if someone adds a new API and forgets to send documentation, or if
it broke the DocBook, I'll also hear an annoying beep, and will reject
the patch.

Not being able to compile just one docbook is a regression and breaks
my process. This needs to be fixed.

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

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.

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.

--

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.

Regards,
Mauro