Path: csiph.com!news.swapon.de!newsfeed.fsmpi.rwth-aachen.de!newsfeed.straub-nv.de!news.unit0.net!takemy.news.telefonica.de!telefonica.de!newsfeed.xs4all.nl!newsfeed7.news.xs4all.nl!nzpost1.xs4all.net!not-for-mail
Return-Path: <python-python-list@m.gmane.org>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
X-Spam-Status: OK 0.008
X-Spam-Evidence: '*H*': 0.98; '*S*': 0.00; 'sphinx': 0.07; 'subject:build': 0.07; 'received:80.91': 0.09; 'received:80.91.229': 0.09; 'received:gmane.org': 0.09; 'received:list': 0.09; 'python': 0.10; 'files.': 0.13; 'up-to- date': 0.13; 'commit': 0.15; 'received:80.91.229.3': 0.16; 'received:dip0.t-ipconnect.de': 0.16; 'received:plane.gmane.org': 0.16; 'received:t-ipconnect.de': 0.16; 'vcs,': 0.16; 'wrote:': 0.16; 'changes': 0.20; 'fairly': 0.22; 'code,': 0.23; 'header :User-Agent:1': 0.26; 'header:X-Complaints-To:1': 0.26; 'subject:skip:d 10': 0.27; 'idea': 0.28; 'code': 0.30; 'especially': 0.32; 'compiled': 0.32; 'source': 0.33; 'instead,': 0.33; 'changing': 0.34; 'so,': 0.35; "isn't": 0.35; 'should': 0.36; 'to:addr:python-list': 0.36; 'subject:: ': 0.37; 'received:org': 0.37; 'anything': 0.38; 'files': 0.38; 'subject:from': 0.39; 'along': 0.39; 'build': 0.40; 'to:addr:python.org': 0.40; 'received:de': 0.40; 'your': 0.60; 'our': 0.64; 'products': 0.70; '\xe2\x80\x93': 0.72; 'directly.': 0.76; 'humans': 0.84; 'subject:source': 0.84; 'imagine': 0.96
X-Injected-Via-Gmane: http://gmane.org/
To: python-list@python.org
From: Peter Otten <__peter__@web.de>
Subject: Re: Automating build from source (was: Automating Sphinx generated documentation)
Date: Fri, 18 Sep 2015 08:50:43 +0200
Organization: None
References: <41302A7145AC054FA7A96CFD03835A0A0B9D749B@EX10MBX02.EU.NEC.COM> <85vbb84nym.fsf@benfinney.id.au>
Mime-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: 8Bit
X-Gmane-NNTP-Posting-Host: p57bd9c52.dip0.t-ipconnect.de
User-Agent: KNode/4.13.3
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.20+
Precedence: list
List-Id: General discussion list for the Python programming language <python-list.python.org>
List-Unsubscribe: <https://mail.python.org/mailman/options/python-list>, <mailto:python-list-request@python.org?subject=unsubscribe>
List-Archive: <http://mail.python.org/pipermail/python-list/>
List-Post: <mailto:python-list@python.org>
List-Help: <mailto:python-list-request@python.org?subject=help>
List-Subscribe: <https://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
Newsgroups: comp.lang.python
Message-ID: <mailman.22.1442559056.16376.python-list@python.org>
Lines: 27
NNTP-Posting-Host: 2001:888:2000:d::a6
X-Trace: 1442559056 news.xs4all.nl 23800 [2001:888:2000:d::a6]:50043
X-Complaints-To: abuse@xs4all.nl
Xref: csiph.com comp.lang.python:96803

Ben Finney wrote:

> David Aldrich <David.Aldrich@EMEA.NEC.COM> writes:
> 
>> I have setup Sphinx for my Python project. We keep all our code and
>> documentation in Subversion.
> 
> It's a good idea to keep *source* files in VCS.
> 
> It's a bad idea to keep automatically-generated files in VCS; it's
> especially bad to do so if they need to be generated again after
> changing the source files.
> 
>> So, following changes to the Python code, I need to regenerate and
>> commit the Sphinx generated documentation.
> 
> Instead, the build products – anything generated automatically by the
> computer, such as the compiled code, compiled documentation – should be
> flagged for “ignore” by the VCS, and never committed.
> 
> The VCS should track only those files that humans edit directly.

Isn't this a case of purity versus practicality? I imagine it might be nice 
to get fairly up-to-date documentation along with your source code checkout 
"for free".