Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #96789 > unrolled thread

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

Back to article view | Back to comp.lang.python

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  Automating build from source (was: Automating Sphinx generated documentation) Ben Finney <ben+python@benfinney.id.au> - 2015-09-18 09:37 +1000
    Re: Automating build from source (was: Automating Sphinx generated documentation) Grant Edwards <invalid@invalid.invalid> - 2015-09-18 01:54 +0000

#96789 — Automating build from source (was: Automating Sphinx generated documentation)

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.

> 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

[toc] | [next] | [standalone]

#96790

On 2015-09-17, Ben Finney <ben+python@benfinney.id.au> wrote:

> The VCS should track only those files that humans edit directly.

While I agree that files automatically generated shouldn't be checked
in to a VCS, I'm in favor of putting key binary files under VCS if
they are required to do the build.  We often check deveopment
toolchains into Subversion.  Subversion handles it just fine, and it
saves having to come up with an entirely different scheme for
archiving toolchain binaries.  [If we build the toolchains ourselves,
we will archive those sources as well.]

--
Grant

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.python

csiph-web