=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 : Fw: python doc build Return-Path: 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 ; 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 ; 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 ; 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 ; 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 ; 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 ; 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 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 To: gentoo-python 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.