From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mauro Carvalho Chehab Subject: Re: [PATCH 2/6] docs-rst: automatically convert Graphviz and SVG images Date: Thu, 2 Mar 2017 12:49:27 -0300 Message-ID: <20170302124927.2aca40e5@vento.lan> References: <20170228171319.1786-1-daniel.vetter@ffwll.ch> <3794838.LWjeBPPEog@avalon> <4887625.tFTYHaRUes@avalon> <1CCE18D2-C7B8-49D3-813E-266554692A94@darmarit.de> <20170302151108.wb34bdv4rvvjblgk@phenom.ffwll.local> <33B82E3D-85F6-4AFA-960F-C26E7969D471@darmarit.de> <20170302124532.65d4652e@vento.lan> Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: <20170302124532.65d4652e@vento.lan> Sender: linux-doc-owner@vger.kernel.org To: Markus Heiser Cc: Daniel Vetter , Laurent Pinchart , Daniel Vetter , dri-devel , Linux Doc Mailing List , Jonathan Corbet , Daniel Vetter List-Id: dri-devel@lists.freedesktop.org Em Thu, 2 Mar 2017 12:45:32 -0300 Mauro Carvalho Chehab escreveu: > Em Thu, 2 Mar 2017 16:21:33 +0100 > Markus Heiser escreveu: > > > Am 02.03.2017 um 16:11 schrieb Daniel Vetter : > > > > > 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 : > > >> > > >>> 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 . 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