Doc build broken

Nic Bernstein nic at onlight.com
Sat Jun 27 10:41:19 EDT 2015


We documentation folk don't have access to the underlying machine on 
which the build tests run, so we can't do anything like that, to the 
best of my knowledge.

The solution I came up with works, for now, and Nicola has requested an 
update of the python stuff on the build host.
     -nic

On 06/27/2015 06:36 AM, John wrote:
> Hi,
>
> I use virtualenv to avoid this kind of pain. It allows the use of 
> python package versions independent of the underlying distribution. Is 
> there a reason that virtualenv could not be used in this case?
>
> John
>
>
> On 26/06/15 22:50, Nic Bernstein wrote:
>> 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 Bernsteinnic 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 Bernsteinnic at onlight.com
>> Onlight, Inc.www.onlight.com
>> 1442 N Farwell Ave., Suite 600            v. 414.272.4477
>> Milwaukee, Wisconsin  53202
>
>

-- 
Nic Bernstein                             nic at onlight.com
Onlight llc.                              www.onlight.com
219 N. Milwaukee St., Ste. 2A	          v. 414.272.4477
Milwaukee, Wisconsin  53202		  f. 414.290.0335

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.andrew.cmu.edu/pipermail/cyrus-devel/attachments/20150627/48929cab/attachment-0001.html 


More information about the Cyrus-devel mailing list