[PATCH 2/6] docs-rst: automatically convert Graphviz and SVG images

[Mauro Carvalho Chehab]

Em Thu, 2 Mar 2017 16:21:33 +0100
Markus Heiser <markus.heiser at darmarit.de> escreveu:

> Am 02.03.2017 um 16:11 schrieb Daniel Vetter <daniel at ffwll.ch>:
> 
> > On Thu, Mar 02, 2017 at 03:58:36PM +0100, Markus Heiser wrote:  
> >> Hi Daniel, Laurent
> >> 
> >> Am 02.03.2017 um 15:14 schrieb Laurent Pinchart <laurent.pinchart at ideasonboard.com>:
> >>   
> >>> Hi Daniel,
> >>> 
> >>> On Thursday 02 Mar 2017 14:54:32 Daniel Vetter wrote:  
> >>>> On Thu, Mar 2, 2017 at 1:26 PM, Laurent Pinchart wrote:  
> >>>>> Hi Daniel,
> >>>>> 
> >>>>> Thank you for the patch.
> >>>>> 
> >>>>> With this applied, I get
> >>>>> 
> >>>>> make[1]: Entering directory '/home/laurent/src/iob/renesas/linux64'
> >>>>> 
> >>>>> SPHINX  htmldocs -->
> >>>>> file:///home/laurent/src/iob/renesas/linux64/Documentation/output PARSE
> >>>>>   include/uapi/linux/videodev2.h
> >>>>> 
> >>>>> Running Sphinx v1.3.1
> >>>>> 
> >>>>> Extension error:
> >>>>> Could not import extension kfigure (exception: cannot import name patches)
> >>>>> make[2]: ***
> >>>>> [/home/laurent/src/iob/renesas/linux/Documentation/Makefile.sphinx:70:
> >>>>> htmldocs] Error 1 make[1]: ***
> >>>>> [/home/laurent/src/iob/renesas/linux/Makefile:1453: htmldocs] Error 2
> >>>>> make[1]: Leaving directory '/home/laurent/src/iob/renesas/linux64' make:
> >>>>> *** [Makefile:152: sub-make] Error 2
> >>>>> 
> >>>>> sphinx.directive.patches got introduced in Sphinx 1.4. If you want to bump
> >>>>> the minimum required version I think a notice is needed.  
> >>>> 
> >>>> Ugh. But this also goes completely over my head, no idea whether we
> >>>> must require sphinx 1.4 (it was released Mar 28, 2016), or whether
> >>>> there's some way to work around this ... Halp?  
> >>> 
> >>> I'm not a Sphinx expert so I don't know, but what I can tell is that copying 
> >>> the patches.py from Sphinx 1.4 to Documentation/sphinx/ and modifying 
> >>> kfigure.py to import it from there fixes the build. There's thus no extra 
> >>> depencency on Sphinx 1.4 (or newer).
> >>> 
> >>> I'm not sure we want to set a precedent by copying part of the Sphinx source 
> >>> code to the kernel tree (or inlining the single small function that the module 
> >>> provides), and I'll let someone more knowledgeable than me decide how to 
> >>> proceed.  
> >> 
> >> 
> >> Aargh ... we need virtualenv! For interim something like the following
> >> might help. In file Documentation/sphinx/kfigure.py edit the imports
> >> 
> >> ...
> >> from docutils.parsers.rst.directives import images
> >> try:
> >>    from sphinx.directives.patches import Figure
> >> except ImportError:
> >>    Figure = images.Figure 
> >> ...
> >> 
> >> And fix the class definition, so it use 'Figure' and no
> >> longer 'patch.Figure'::
> >> 
> >> ...
> >> -class KernelFigure(patches.Figure):
> >> +class KernelFigure(Figure):
> >> ...
> >> 
> >> Sorry that I have not yet the time to send you a decent and tested
> >> patch. Do you like to test my suggestion? / thanks!  
> > 
> > I'll give it a shot at implementing it, but I can't (easily at least) test
> > on sphinx 1.3.  
> 
> You can test it with virtualenv  https://virtualenv.pypa.io/en/stable/userguide/
> 
> In short:
> 
> $ cd kernel-src
> $ virtualenv myenv
> $ source myenv/bin/activate
> $ pip install 'Sphinx==1.3.1'
> $ make ....

Hmm... at least here, building docs-next with Sphinx 1.3.1 inside a
virtualenv is broken:

writing output... [ 16%] media/intro                                            
Exception occurred:
  File "/devel/v4l/patchwork/myenv-1.3/lib/python2.7/site-packages/docutils/writers/_html_base.py", line 671, in depart_document
    assert not self.context, 'len(context) = %s' % len(self.context)
AssertionError: len(context) = 1
The full traceback has been saved in /tmp/sphinx-err-W7CPtT.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
Documentation/Makefile.sphinx:69: recipe for target 'htmldocs' failed
make[1]: *** [htmldocs] Error 1
Makefile:1450: recipe for target 'htmldocs' failed
make: *** [htmldocs] Error 2

Perhaps it is time for us to move minimal requirements to 1.4?

Thanks,
Mauro