[PATCH 2/6] docs-rst: automatically convert Graphviz and SVG images
Mauro Carvalho Chehab
mchehab at s-opensource.com
Thu Mar 2 15:49:27 UTC 2017
Em Thu, 2 Mar 2017 12:45:32 -0300
Mauro Carvalho Chehab <mchehab at s-opensource.com> escreveu:
> 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?
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
More information about the dri-devel
mailing list