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

[Jonathan Corbet]

On Thu, 2 Mar 2017 16:09:21 -0300
Mauro Carvalho Chehab <mchehab at 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.

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.  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.

 - 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.

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.

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

jon