[gentoo-python] Fwd: python doc build

[gentoo-python] Fwd: python doc build

[Alex Brandt]

[-- Attachment #1.1: Type: text/plain, Size: 6382 bytes --]

=2D-nextPart11109560.VMH94fZKDn
Content-Transfer-Encoding: 7Bit
Content-Type: text/plain; charset="us-ascii"

Hey Guys,

Ian's been having difficulties getting this to the list, so I'm 
forwarding it on his behalf.

Thanks,

=2D- 
Alex Brandt
Cloud Evangelist for Rackspace and Developer for Gentoo
http://blog.alunduil.com

=2D-nextPart11109560.VMH94fZKDn
Content-Type: message/rfc822
Content-Disposition: inline; filename="forwarded message"
Content-Description: IAN DELANEY <della5@iinet.com.au>: Fw: python doc build

Return-Path: <della5@iinet.com.au>
X-Original-To: alunduil@alunduil.com
Delivered-To: alunduil@alunduil.com
Received: from localhost (giskard.alunduil.com [127.0.0.1]) by giskard.alunduil.com (Postfix) with ESMTP id EC0964492D for <alunduil@alunduil.com>; Sat, 13 Sep 2014 21:51:40 -0500 (CDT)
X-Virus-Scanned: amavisd-new at alunduil.com
Received: from giskard.alunduil.com ([127.0.0.1]) by localhost (giskard.alunduil.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id sQ_Y-kywM2Vo for <alunduil@alunduil.com>; Sat, 13 Sep 2014 21:51:39 -0500 (CDT)
Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) by giskard.alunduil.com (Postfix) with ESMTPS id 7904F4492C for <alunduil@alunduil.com>; Sat, 13 Sep 2014 21:51:38 -0500 (CDT)
Received: by smtp.gentoo.org (Postfix) id 0EE563401B0; Sun, 14 Sep 2014 02:51:37 +0000 (UTC)
Delivered-To: alunduil@gentoo.org
Received: from localhost (localhost [127.0.0.1]) by smtp.gentoo.org (Postfix) with ESMTP id 04D5C3400EB for <alunduil@gentoo.org>; Sun, 14 Sep 2014 02:51:37 +0000 (UTC)
X-Virus-Scanned: by amavisd-new using ClamAV at gentoo.org
Received: from smtp.gentoo.org ([IPv6:::ffff:127.0.0.1]) by localhost (smtp.gentoo.org [IPv6:::ffff:127.0.0.1]) (amavisd-new, port 10024) with ESMTP id v2XxwNxHIz4c for <alunduil@gentoo.org>; Sun, 14 Sep 2014 02:51:30 +0000 (UTC)
Received: from icp-osb-irony-out9.external.iinet.net.au (icp-osb-irony-out9.external.iinet.net.au [203.59.1.226]) by smtp.gentoo.org (Postfix) with ESMTP id BF9AA33F2BF for <alunduil@gentoo.org>; Sun, 14 Sep 2014 02:51:28 +0000 (UTC)
X-IronPort-Anti-Spam-Filtered: true
X-IronPort-Anti-Spam-Result: AjcLADwBFVR8lGpG/2dsb2JhbABfgw1TV7FtBAIGlxQKh06BChZ4hAMBAgUCN1oNBAMBAgo0EAklAg4TiD0Ol2KkQBiFfIhvEQFdhEUFiz2GE4Q0hAEyglCBOSeGEY1Pg2swLwGBDoE7AQEB
X-IronPort-AV: E=Sophos;i="5.04,520,1406563200"; d="scan'208";a="549348376"
Received: from unknown (HELO archtester.homenetwork) ([124.148.106.70]) by icp-osb-irony-out9.iinet.net.au with ESMTP; 14 Sep 2014 10:51:27 +0800
Date: Sun, 14 Sep 2014 10:41:50 +0800
From: IAN DELANEY <della5@iinet.com.au>
To: alunduil@gentoo.org, alunduil@gentoo.org
Subject: Fw: python doc build
Message-ID: <20140914104150.4491d427@archtester.homenetwork>
Organization: homenetwork
X-Mailer: Claws Mail 3.9.0 (GTK+ 2.24.23; x86_64-pc-linux-gnu)
MIME-Version: 1.0
Content-Type: text/plain; charset="US-ASCII"
Content-Transfer-Encoding: 7bit



Begin forwarded message:

Date: Sun, 14 Sep 2014 10:41:25 +0800
From: IAN DELANEY <idella4@gentoo.org>
To: gentoo-python <gentoo-python@lists.gentoo.org>
Subject: python doc build




A recent addition to the tree in the form of portage of flask-cors
warrants this email re doc builds in python packages.  No need to copy
the bash code here, just peruse the ebuild of dev-python/flask-cors.
The ebuild redirects conf.py to an installed objects.inv because the
doc build merrily d'loads it from the i'net.  The investigating took
days of pursuit to both source the pertinent rules and make the workable
code to edit conf.py.  The ebuild avoids network access [1,2] by finding
the objects.inv installed by python-docs [3] with equery and adjusting
conf.py appropriately.

Patrick is one who vouches for the wrongness of a doc build d'loading
from=20the net citing its inevitable failure in a build style server with
no i'net connection. At least one other dev listed in the python team
agrees this is 'wrong practice', yet others from past exchanges when
highlighted, more or less said 'so what'. Whether the code in this
ebuild warrants adopting by/in these many other ebuilds that do
pythonic doc builds is the topic here. Sadly the length to achieve the
goal of referencing a tiny file makes it look like the proverbial bike
shed.  So much effort for such a tiny reward. I recently edited the
python-docs ebuilds to add installing of the file that has always been
there.

Pros; 

    it's the right thing to do that honours the rule to not allow
or require network access during the build.  (The dev manual is very
piece meal with this. [1,2]) It refers to it here and there but never
says explicitly "network access during these phases is disallowed"

    the doc build is done how its was intended by upstream in full

Cons;
    the length multiplied by the zillions of pythonic doc builds will
occupy quite some space.

    there are some rare doc builds that import 2-3 separate objects.inv
    files from docs of other dep packages.

    No-one has ever noticed or complained before except possibly
flameeys back in the day before he took the hint and stopped
filing copious bugs to the python team for breaches of network
access, unicode failures & anything else he could lay his hands on.
(I believe this is what first made me notice this)   

    Therefore there is virtually no history of bugs filed saying my
local buildbot failed python doc builds here here and here.

    It would beckon a large number of edits / commits to repair those
zillions of packages which no-one has complained about.

On my part, I have long since used a fix whereby the use of
intersphinx is knocked out in conf.py.  Initially I made patches
before finally discovering it could be knocked out in a one line
sed statement, now prevalent in many packages.  Just as with the doc
build itself, there is no history of bugs reporting "Oh the links of
the doc build are faulty and missing content".  The purist in me says
adopt this code for doc builds that are coded to d'load objects.inv
file(s) but the pragmatist says no.


[1]: https://bugs.gentoo.org/show_bug.cgi?id=522064
[2]: https://github.com/gentoo/devmanual.gentoo.org/pull/21
[3]: https://bugs.gentoo.org/show_bug.cgi?id=521768

=2D- 
kind regards

Ian Delaney


=2D- 
kind regards

Ian Delaney


=2D- 
kind regards

Ian Delaney

=2D-nextPart11109560.VMH94fZKDn--
This is a multi-part message in MIME format.

[-- Attachment #1.2: Type: text/plain, Size: 212 bytes --]

Hey Guys,

Ian's been having difficulties getting this to the list, so I'm 
forwarding it on his behalf.

Thanks,

-- 
Alex Brandt
Cloud Evangelist for Rackspace and Developer for Gentoo
http://blog.alunduil.com

[-- Attachment #1.3: IAN DELANEY <della5@iinet.com.au>: Fw: python doc build --]
[-- Type: message/rfc822, Size: 5772 bytes --]

From: IAN DELANEY <della5@iinet.com.au>
To: alunduil@gentoo.org, alunduil@gentoo.org
Subject: Fw: python doc build
Date: Sun, 14 Sep 2014 10:41:50 +0800
Message-ID: <20140914104150.4491d427@archtester.homenetwork>



Begin forwarded message:

Date: Sun, 14 Sep 2014 10:41:25 +0800
From: IAN DELANEY <idella4@gentoo.org>
To: gentoo-python <gentoo-python@lists.gentoo.org>
Subject: python doc build




A recent addition to the tree in the form of portage of flask-cors
warrants this email re doc builds in python packages.  No need to copy
the bash code here, just peruse the ebuild of dev-python/flask-cors.
The ebuild redirects conf.py to an installed objects.inv because the
doc build merrily d'loads it from the i'net.  The investigating took
days of pursuit to both source the pertinent rules and make the workable
code to edit conf.py.  The ebuild avoids network access [1,2] by finding
the objects.inv installed by python-docs [3] with equery and adjusting
conf.py appropriately.

Patrick is one who vouches for the wrongness of a doc build d'loading
from the net citing its inevitable failure in a build style server with
no i'net connection. At least one other dev listed in the python team
agrees this is 'wrong practice', yet others from past exchanges when
highlighted, more or less said 'so what'. Whether the code in this
ebuild warrants adopting by/in these many other ebuilds that do
pythonic doc builds is the topic here. Sadly the length to achieve the
goal of referencing a tiny file makes it look like the proverbial bike
shed.  So much effort for such a tiny reward. I recently edited the
python-docs ebuilds to add installing of the file that has always been
there.

Pros; 

    it's the right thing to do that honours the rule to not allow
or require network access during the build.  (The dev manual is very
piece meal with this. [1,2]) It refers to it here and there but never
says explicitly "network access during these phases is disallowed"

    the doc build is done how its was intended by upstream in full

Cons;
    the length multiplied by the zillions of pythonic doc builds will
occupy quite some space.

    there are some rare doc builds that import 2-3 separate objects.inv
    files from docs of other dep packages.

    No-one has ever noticed or complained before except possibly
flameeys back in the day before he took the hint and stopped
filing copious bugs to the python team for breaches of network
access, unicode failures & anything else he could lay his hands on.
(I believe this is what first made me notice this)   

    Therefore there is virtually no history of bugs filed saying my
local buildbot failed python doc builds here here and here.

    It would beckon a large number of edits / commits to repair those
zillions of packages which no-one has complained about.

On my part, I have long since used a fix whereby the use of
intersphinx is knocked out in conf.py.  Initially I made patches
before finally discovering it could be knocked out in a one line
sed statement, now prevalent in many packages.  Just as with the doc
build itself, there is no history of bugs reporting "Oh the links of
the doc build are faulty and missing content".  The purist in me says
adopt this code for doc builds that are coded to d'load objects.inv
file(s) but the pragmatist says no.


[1]: https://bugs.gentoo.org/show_bug.cgi?id=522064
[2]: https://github.com/gentoo/devmanual.gentoo.org/pull/21
[3]: https://bugs.gentoo.org/show_bug.cgi?id=521768

-- 
kind regards

Ian Delaney


-- 
kind regards

Ian Delaney


-- 
kind regards

Ian Delaney

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 213 bytes --]