Re: docutils borkage (was: [PATCH 2/6] docs-rst: automatically convert Graphviz and SVG images)

From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
To: Jonathan Corbet <corbet@lwn.net>
Cc: Markus Heiser <markus.heiser@darmarit.de>,
	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>,
	Daniel Vetter <daniel.vetter@intel.com>
Subject: Re: docutils borkage (was: [PATCH 2/6] docs-rst: automatically convert Graphviz and SVG images)
Date: Sat, 4 Mar 2017 23:23:18 -0300	[thread overview]
Message-ID: <20170304232318.6cbfd337@vento.lan> (raw)
In-Reply-To: <20170304075652.75737cd3@lwn.net>

Em Sat, 4 Mar 2017 07:56:52 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Thu, 2 Mar 2017 16:09:21 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > IMHO, the way Python and python libraries break compatibility is crazy.
> > 
> > Good packaging sense says that, if APIs can break on every single new
> > release (with seems to be the case of docutils), then a package
> > depending on such bad-developed library should require the exact
> > version(s) it is known to work.
> > 
> > When we're discussing about the docs toolchain, I mentioned that I
> > was afraid that the Python development model would cause this sort
> > of issues. Unfortunately, it seems that my concerns were pertinent :-(  
> 
> It doesn't have to be that way...  The LWN site is a Python application
> that has been running since 2002 without any significant issues of this
> type, despite having some significant external dependencies.  There is
> nothing inherent in Python that creates this kind of mess, it's really
> just a matter of having the same discipline that you need when writing a
> library in any other language.
> 
> It would appear that this discipline is severely lacking in the docutils
> camp in particular.

>From the answer for this bug at:
	https://github.com/sphinx-doc/sphinx/issues/3212

It seems that Sphinx maintainers don't care enough to avoid those
issues either.

> One way kids these days handle such issues is to just bundle up all the
> dependencies they are about and ship their own copies.  This isn't just
> Python; see https://lwn.net/Articles/712318/ for some much worse
> examples. 

Yeah, the direction they're taken is, IMHO, a bad idea.

> But I don't think we want to do that.
> 
> There does not appear to be an ideal solution here.  I wonder if we want
> do to something like this:
> 
>  - Put in a little test program to verify that the build system has
>    versions of sphinx and docutils that play well together.

I wrote something like that some time ago, meant to build the media
drivers on legacy Kernels:
	https://git.linuxtv.org/media_build.git/tree/build

Perhaps some of the ideas there could be used on such script. The logic
there identifies the distribution, via either lsb or by reading some
files at /etc:

	$system_release = qx(lsb_release -d) if which("lsb_release");
	$system_release =~ s/Description:\s*// if ($system_release);
	$system_release = catcheck("/etc/system-release") if !$system_release;
	$system_release = catcheck("/etc/redhat-release") if !$system_release;
	$system_release = catcheck("/etc/lsb-release") if !$system_release;
	$system_release = catcheck("/etc/gentoo-release") if !$system_release;
	$system_release = catcheck("/etc/issue") if !$system_release;
	$system_release =~ s/\s+$//;

and presents distro-specific commands and package names:

	sub give_hints()
	{

		# Distro-specific hints
		if ($system_release =~ /Red Hat Enterprise Linux/) {
			give_redhat_hints;
			return;
		}
		if ($system_release =~ /Fedora/) {
			give_redhat_hints;
			return;
		}
		if ($system_release =~ /Ubuntu/) {
			give_ubuntu_hints;
			return;
		}
	...

I guess your idea would be to run such test program if someone calls make
with htmldocs target, right? It will still need to check also for the
LaTex packages needed for Math symbols support.

It could make sense to also run it for pdfdocs, although the LaTex
dependencies for it can be harder for us to identify.

>  - Add a script to create a working combination in a virtualenv for
>    people who need it.  If the build process sees one of those in place,
>    it should use it.

Makes sense. The test program could present both alternatives to the
user (manually install required packages or run the virtualenv
creation script).

> I feel pretty strongly that the build should *not* just go off and do the
> virtualenv thing automatically.  We should not be fetching and installing
> external software on somebody's system, even in a contained environment,
> without an explicit request to do so.

Agreed.

> Look for a grumpy article on your favorite news site in the relatively
> near future...:)

Sounds good :-)

Thanks,
Mauro