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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html