Doc build broken
Nic Bernstein
nic at onlight.com
Fri Jun 26 17:50:13 EDT 2015
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 nic at 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 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/41af995e/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/41af995e/attachment.vcf
More information about the Cyrus-devel
mailing list