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

From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
To: Markus Heiser <markus.heiser@darmarit.de>
Cc: Daniel Vetter <daniel@ffwll.ch>,
	Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
	Daniel Vetter <daniel.vetter@ffwll.ch>,
	dri-devel <dri-devel@lists.freedesktop.org>,
	Linux Doc Mailing List <linux-doc@vger.kernel.org>,
	Jonathan Corbet <corbet@lwn.net>,
	Daniel Vetter <daniel.vetter@intel.com>
Subject: Re: [PATCH 2/6] docs-rst: automatically convert Graphviz and SVG images
Date: Thu, 2 Mar 2017 13:29:35 -0300	[thread overview]
Message-ID: <20170302132935.2d524cb3@vento.lan> (raw)
In-Reply-To: <24831FFC-9A33-432D-A13B-A908A07D3308@darmarit.de>

Em Thu, 2 Mar 2017 17:13:25 +0100
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> > Am 02.03.2017 um 16:49 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> >   
> >>> 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  
> ....
> >  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  
> 
> I guess this is a error from newer docutils, so we have to fix docutils version also.
> 
> Sphinx itself specifies "docutils>=0.11"
> 
>   https://github.com/sphinx-doc/sphinx/blob/1.3.1/setup.py#L52
> 
> So I guess it uses a up to date docutils or the ducutils which are already installed system wide.

The system-wide docutils is this one:

	python2-docutils-0.13.1-3.fc25.noarch
	python3-docutils-0.13.1-3.fc25.noarch

Btw, I tested also with virtualenv-3/pip3 and the same issue happens there.

Manually installing version 0.11 makes it to work again.

Considering that Sphinx require a specific docutils package for it to
work, perhaps it is time for us to consider to use the virtenv
enchantments at make docs targets :-p

Thanks,
Mauro