<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
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.<br>
<br>
The solution I came up with works, for now, and Nicola has requested
an update of the python stuff on the build host.<br>
-nic<br>
<br>
<div class="moz-cite-prefix">On 06/27/2015 06:36 AM, John wrote:<br>
</div>
<blockquote cite="mid:558E8AD2.7010307@earthspike.net" type="cite">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<div class="moz-cite-prefix">Hi,<br>
<br>
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?<br>
<br>
John<br>
<br>
<br>
On 26/06/15 22:50, Nic Bernstein wrote:<br>
</div>
<blockquote class=" cite" id="mid_558DC915_1020900_onlight_com"
cite="mid:558DC915.1020900@onlight.com" type="cite">
<meta content="text/html; charset=UTF-8"
http-equiv="Content-Type">
Nicola,<br>
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 <a moz-do-not-send="true"
href="https://git.cyrus.foundation/diffusion/D/browse/master/source/exts/sphinxlocal/writers/manpage.py">cyrus-docs/source/exts/sphinxlocal/writes/manpage.py</a>.<br>
<br>
This is a total, absolute and unrepentant hack, but it does
work, it builds on Wheezy, and even harbormaster is happy (see <a
moz-do-not-send="true"
href="https://git.cyrus.foundation/B2110">B2110</a>). <a
moz-do-not-send="true" class="moz-txt-link-freetext"
href="https://docs.cyrus.foundation/">https://docs.cyrus.foundation/</a>
is now up to date and has all of your changes as well as mine.<br>
<br>
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.<br>
<br>
Cheers,<br>
-nic<br>
<br>
<div class="moz-cite-prefix">On 06/26/2015 04:40 PM, Nicola Nye
wrote:<br>
</div>
<blockquote class=" cite"
id="mid_1435354815_3617542_308862793_7ACE8791_webmail_messagingengine_com"
cite="mid:1435354815.3617542.308862793.7ACE8791@webmail.messagingengine.com"
type="cite">
<pre wrap="">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:
</pre>
<blockquote class=" cite" id="Cite_8143232" type="cite">
<pre wrap="">On 06/25/2015 11:01 PM, Nicola Nye wrote:
</pre>
<blockquote class=" cite" id="Cite_4245171" type="cite">
<pre wrap="">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.
<a moz-do-not-send="true" class="moz-txt-link-freetext" href="https://git.cyrus.foundation/harbormaster/build/964/">https://git.cyrus.foundation/harbormaster/build/964/</a>
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
</pre>
</blockquote>
<pre wrap="">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 <a moz-do-not-send="true" class="moz-txt-link-abbreviated" href="mailto:nic@onlight.com">nic@onlight.com</a>
Onlight, Inc. <a moz-do-not-send="true" class="moz-txt-link-abbreviated" href="http://www.onlight.com">www.onlight.com</a>
1442 N Farwell Ave., Suite 600 v. 414.272.4477
Milwaukee, Wisconsin 53202
Email had 1 attachment:
+ nic.vcf
1k (text/x-vcard)
</pre>
</blockquote>
</blockquote>
<br>
<pre class="moz-signature" cols="72">--
Nic Bernstein <a moz-do-not-send="true" class="moz-txt-link-abbreviated" href="mailto:nic@onlight.com">nic@onlight.com</a>
Onlight, Inc. <a moz-do-not-send="true" class="moz-txt-link-abbreviated" href="http://www.onlight.com">www.onlight.com</a>
1442 N Farwell Ave., Suite 600 v. 414.272.4477
Milwaukee, Wisconsin 53202
</pre>
</blockquote>
<br>
<br>
</blockquote>
<br>
<pre class="moz-signature" cols="72">--
Nic Bernstein <a class="moz-txt-link-abbreviated" href="mailto:nic@onlight.com">nic@onlight.com</a>
Onlight llc. <a class="moz-txt-link-abbreviated" href="http://www.onlight.com">www.onlight.com</a>
219 N. Milwaukee St., Ste. 2A v. 414.272.4477
Milwaukee, Wisconsin 53202 f. 414.290.0335
</pre>
</body>
</html>