Automating build from source (was: Automating Sphinx generated documentation)
ben+python at benfinney.id.au
Fri Sep 18 01:37:21 CEST 2015
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.
> I just wondered how people manage this. I'm thinking of using Jenkins
> (a continuous integration tool) to check for changes, regenerate the
> docs and check them in.
Deploying the code base, whether for testing or to staging or production
or wherever, should entail a build step. That build step is responsible
for going from source-files-only, checked out from the VCS, to a
complete ready-to-deploy tree of files.
That build step should always start from a clean source tree, so that
you always know the end result reflects what was committed to VCS.
Build tools include old-school Makefile, or newer tools like Meson.
Note that this is automated build. This is a different question from
automated deployment (you might like Fabric for that), and is a
different question from automated integration (you might like Jenkins
First, though, you need an automated build, so you can separate “what's
tracked in VCS” versus “what's generated automatically”.
\ “If we listen only to those who are like us, we will squander |
`\ the great opportunity before us: To live together peacefully in |
_o__) a world of unresolved differences.” —David Weinberger |
More information about the Python-list