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

[Mauro Carvalho Chehab <mchehab@s-opensource.com>]

Em Thu, 2 Mar 2017 12:45:32 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> escreveu:

> Em Thu, 2 Mar 2017 16:21:33 +0100
> Markus Heiser <markus.heiser@darmarit.de> escreveu:
> 
> > Am 02.03.2017 um 16:11 schrieb Daniel Vetter <daniel@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@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?

Hmm... the same happened with 1.4.9 inside virtualenv. It built fine
with 1.5.2 (for htmldocs).

Thanks,
Mauro

-

This is the error log with 1.4:

# Sphinx version: 1.4.9
# Python version: 2.7.13 (CPython)
# Docutils version: 0.13.1 release
# Jinja2 version: 2.9.5
# Last messages:
#   writing output... [ 18%] media/dvb-drivers/faq
#   writing output... [ 18%] media/dvb-drivers/index
#   writing output... [ 18%] media/dvb-drivers/intro
#   writing output... [ 18%] media/dvb-drivers/lmedm04
#   writing output... [ 18%] media/dvb-drivers/opera-firmware
#   writing output... [ 18%] media/dvb-drivers/technisat
#   writing output... [ 19%] media/dvb-drivers/ttusb-dec
#   writing output... [ 19%] media/dvb-drivers/udev
#   writing output... [ 19%] media/index
#   writing output... [ 19%] media/intro
# Loaded extensions:
#   kernel_include (1.0) from /devel/v4l/patchwork/Documentation/sphinx/kernel_include.pyc
#   rstFlatTable (1.0) from /devel/v4l/patchwork/Documentation/sphinx/rstFlatTable.pyc
#   cdomain (1.0) from /devel/v4l/patchwork/Documentation/sphinx/cdomain.pyc
#   kerneldoc (1.0) from /devel/v4l/patchwork/Documentation/sphinx/kerneldoc.pyc
#   alabaster (0.7.10) from /devel/v4l/patchwork/myenv-1.4/lib/python2.7/site-packages/alabaster/__init__.pyc
#   sphinx.ext.imgmath (1.4.9) from /devel/v4l/patchwork/myenv-1.4/lib/python2.7/site-packages/sphinx/ext/imgmath.pyc
Traceback (most recent call last):
  File "/devel/v4l/patchwork/myenv-1.4/lib/python2.7/site-packages/sphinx/cmdline.py", line 244, in main
    app.build(opts.force_all, filenames)
  File "/devel/v4l/patchwork/myenv-1.4/lib/python2.7/site-packages/sphinx/application.py", line 297, in build
    self.builder.build_update()
  File "/devel/v4l/patchwork/myenv-1.4/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 251, in build_update
    'out of date' % len(to_build))
  File "/devel/v4l/patchwork/myenv-1.4/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 322, in build
    self.write(docnames, list(updated_docnames), method)
  File "/devel/v4l/patchwork/myenv-1.4/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 360, in write
    self._write_serial(sorted(docnames), warnings)
  File "/devel/v4l/patchwork/myenv-1.4/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 368, in _write_serial
    self.write_doc(docname, doctree)
  File "/devel/v4l/patchwork/myenv-1.4/lib/python2.7/site-packages/sphinx/builders/html.py", line 448, in write_doc
    self.docwriter.write(doctree, destination)
  File "/devel/v4l/patchwork/myenv-1.4/lib/python2.7/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/devel/v4l/patchwork/myenv-1.4/lib/python2.7/site-packages/sphinx/writers/html.py", line 47, in translate
    self.document.walkabout(visitor)
  File "/devel/v4l/patchwork/myenv-1.4/lib/python2.7/site-packages/docutils/nodes.py", line 187, in walkabout
    visitor.dispatch_departure(self)
  File "/devel/v4l/patchwork/myenv-1.4/lib/python2.7/site-packages/docutils/nodes.py", line 1895, in dispatch_departure
    return method(node)
  File "/devel/v4l/patchwork/myenv-1.4/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