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...@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)
