Doc build broken

Nic Bernstein nic at
Fri Jun 26 17:50:13 EDT 2015

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 

This is a total, absolute and unrepentant hack, but it does work, it 
builds on Wheezy, and even harbormaster is happy (see B2110 
<>). 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.


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.
>>> 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/ 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/, 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/  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                             nic at
>> Onlight, Inc.                   
>> 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                             nic at
Onlight, Inc.                   
1442 N Farwell Ave., Suite 600            v. 414.272.4477
Milwaukee, Wisconsin  53202

-------------- next part --------------
An HTML attachment was scrubbed...
-------------- next part --------------
A non-text attachment was scrubbed...
Name: nic.vcf
Type: text/x-vcard
Size: 271 bytes
Desc: not available
Url : 

More information about the Cyrus-devel mailing list