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

[Chris Angelico]

On Fri, Sep 18, 2015 at 9:37 AM, Ben Finney <ben+python at benfinney.id.au> 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.

While I broadly agree, I would say this is a case of code smell rather
than something outright verboten. There are a few situations where
it's easier to commit the generated files as well; for instance, it
can help you get around a bootstrapping problem - you use a previous
build of Python to generate the frozen importlib, I think, and use
that to build the next Python. (If that's not how CPython is built, my
apologies; there are other projects that _do_ use this method, so it's
just a flawed example.) If you don't commit the generated files,
someone who wants to build from source has to first pick up a
precompiled binary or somesuch. (Or, looking the other way:
Disallowing generated files in source control restricts the generator
to something that's already available on every build system.)

But yes, as a general rule, I prefer to list all generated files in
.gitignore or equivalent.

ChrisA