David Aldrich <david.aldr...@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 -- https://mail.python.org/mailman/listinfo/python-list
