Automating build from source (was: Automating Sphinx generated documentation)

Peter Otten __peter__ at web.de
Fri Sep 18 08:50:43 CEST 2015


Ben Finney wrote:

> David Aldrich <David.Aldrich at 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".




More information about the Python-list mailing list