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

[Ben Finney]

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
for that).

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 |
Ben Finney