Doc build broken

[Nic Bernstein]

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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.andrew.cmu.edu/pipermail/cyrus-devel/attachments/20150626/74bf414f/attachment.html 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: nic.vcf
Type: text/x-vcard
Size: 271 bytes
Desc: not available
Url : http://lists.andrew.cmu.edu/pipermail/cyrus-devel/attachments/20150626/74bf414f/attachment.vcf