Hi, I use virtualenv to avoid this kind of pain. It allows the use of python package versions independent of the underlying distribution. Is there a reason that virtualenv could not be used in this case?
John On 26/06/15 22:50, Nic Bernstein wrote: > Nicola, > No rush. I put on my big-boy pants and got this sorted. In effect I > took every change between docutils v0.8.1 & v0.11.3, and between > sphinx v1.1.2 & v1.2.3 and incorporated them verbatim in the bottom of > our cyrus-docs/source/exts/sphinxlocal/writes/manpage.py > <https://git.cyrus.foundation/diffusion/D/browse/master/source/exts/sphinxlocal/writers/manpage.py>. > > This is a total, absolute and unrepentant hack, but it does work, it > builds on Wheezy, and even harbormaster is happy (see B2110 > <https://git.cyrus.foundation/B2110>). https://docs.cyrus.foundation/ > is now up to date and has all of your changes as well as mine. > > I commented the start of the ugly hack quite clearly, so we can lop it > off if and when we ever do get modern versions of the toolset installed. > > Cheers, > -nic > > On 06/26/2015 04:40 PM, Nicola Nye wrote: >> Hi Nic, >> >> Yes! Spot on. I remember looking into the Sphinx versions when I first >> started and then promptly forgot about it. >> >> I totally agree about your proposed versions. I'll chase down Jeroen who >> I think has the keys to that box and see if we can't get it brought up >> to date. Or at least out of the dark ages. >> >> Cheers, >> >> Nicola >> >> On Sat, Jun 27, 2015, at 05:28 AM, Nic Bernstein wrote: >>> On 06/25/2015 11:01 PM, Nicola Nye wrote: >>>> Hi Nic, >>>> >>>> After some false starts using arc, I finally got a bunch of my changes >>>> committed through onto the cyrus docs tree. And then I noticed the >>>> website wasn't updating. >>>> >>>> After some help from ellie, it turns out our doc build broke a while ago >>>> and we hadn't noticed! >>>> >>>> I think it has to do with the new man page builder you wrote. >>>> Developer's lament: it works for me (and for you!) but for some reason >>>> it looks like it's falling over on the server. >>>> >>>> https://git.cyrus.foundation/harbormaster/build/964/ >>>> >>>> School holidays are here for the next couple of weeks so I'm on reduced >>>> hours but I'll be checking in to see if I can also work out what's going >>>> on. >>>> >>>> Cheers, >>>> >>>> Nicola >>> Nicola, >>> Note sure what to do about this. I've spent the day bringing up a >>> Wheezy VM to play with this stuff, and made a version of >>> writer/manpage.py which works, but there's lots of other problems with >>> the old python-docutils which I could spend the next month trying to >>> work around. >>> >>> Wheezy uses Sphinx v1.1.3 (2012-03-10) and docutils v0.8.1, which dates >>> from 2011-08-31. There's been a lot of changes since then, some of >>> which had to do with basic functionality. For example, in >>> docutils-0.8.1, in writer/manpage.py, is this definition: >>> >>> def visit_Text(self, node): >>> text = node.astext() >>> text = text.replace('\\','\\e') >>> replace_pairs = [ >>> (u'-', ur'\-'), >>> (u'\'', ur'\(aq'), >>> (u'ยด', ur'\''), >>> (u'`', ur'\(ga'), >>> ] >>> for (in_char, out_markup) in replace_pairs: >>> text = text.replace(in_char, out_markup) >>> # unicode >>> text = self.deunicode(text) >>> if self._in_literal: >>> # prevent interpretation of "." at line start >>> if text[0] == '.': >>> # << BUG >>> text = '\\&' + text >>> text = text.replace('\n.', '\n\\&.') >>> self.body.append(text) >>> >>> The line "if text[0] == '.':" is a flat out bug, since if 'text' is ever >>> empty, it fails. This bug was fixed in release 0.11 (2013-07-22), with >>> this line: >>> >>> if text.startswith('.'): >>> >>> So in order to get manpages to build _at all_, I need to redefine >>> visit_Text in our custom writer/manpage.py. I've done so, but that's >>> just the start of the problems. >>> >>> I would like to propose that we get a newer version of python-docutils >>> and python-sphinx installed on harbormaster and declare that certain >>> minimum versions of both packages are required to build documentation >>> from source. For the record, I further propose that these be: >>> >>> * python-docutils-0.11.3 >>> * python-sphinx-1.2.2 >>> >>> By the way, those are the versions which are supported by Ubuntu Trusty >>> (14.04.2) and Utopic (14.10); Debian Jessie and Sid; Fedora 20 & 21; >>> etc. This is not bleeding edge stuff, but at least it doesn't suffer >>> from long-ago fixed bugs. >>> >>> Building Cyrus documentation from source is a different proposition from >>> building the server from source. It's my understanding that the >>> manpages, in particular, are to be built and included, pre-built, in the >>> cyrus-imapd distribution package. So as long as _we_ can build the >>> manpages, we're golden (as they say). >>> >>> That's why I feel comfortable recommending that we ask that a newer >>> version of these tools be installed on harbormaster. >>> >>> Your thoughts? >>> -nic >>> >>> -- >>> Nic Bernstein n...@onlight.com >>> Onlight, Inc. www.onlight.com >>> 1442 N Farwell Ave., Suite 600 v. 414.272.4477 >>> Milwaukee, Wisconsin 53202 >>> >>> Email had 1 attachment: >>> + nic.vcf >>> 1k (text/x-vcard) > > -- > Nic Bernstein n...@onlight.com > Onlight, Inc. www.onlight.com > 1442 N Farwell Ave., Suite 600 v. 414.272.4477 > Milwaukee, Wisconsin 53202
