Re: Doc build broken

Fri, 26 Jun 2015 12:29:41 -0700 

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

<<attachment: nic.vcf>>

Reply via email to