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, NicolaNicola, 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
<<attachment: nic.vcf>>
