Doc build broken

John john-cyrus at earthspike.net
Sat Jun 27 07:36:50 EDT 2015


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 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/20150627/4c329761/attachment.html 


More information about the Cyrus-devel mailing list