From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mauro Carvalho Chehab 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 Message-ID: <20170304232318.6cbfd337@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> <20170302124927.2aca40e5@vento.lan> <24831FFC-9A33-432D-A13B-A908A07D3308@darmarit.de> <20170302132935.2d524cb3@vento.lan> <20170302160921.3366847d@vento.lan> <20170304075652.75737cd3@lwn.net> Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 8BIT Return-path: In-Reply-To: <20170304075652.75737cd3@lwn.net> Sender: linux-doc-owner@vger.kernel.org To: Jonathan Corbet Cc: Markus Heiser , Daniel Vetter , Laurent Pinchart , Daniel Vetter , dri-devel , Linux Doc Mailing List , Daniel Vetter List-Id: dri-devel@lists.freedesktop.org Em Sat, 4 Mar 2017 07:56:52 -0700 Jonathan Corbet escreveu: > On Thu, 2 Mar 2017 16:09:21 -0300 > Mauro Carvalho Chehab 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