Supported python versions, pre-commit tests, sphinx

[Ian Clatworthy]

On 02/06/10 09:28, Robert Collins wrote:
> Currently we support python2.4 and up, and build optional docs via
> sphinx. sphinx seems to be nicer than what we were using before, and
> Ian wants to delete the old cruft:)

Yes please. Supporting multiple doc toolchains is unnecessary 
complexity. Sphinx just keeps getting better and better as well, e.g. 
the beta of Sphinx 1.0 has three new builders:

* epub
* man pages
* single-file HTML

Hmmm - can't wait.

> However our pre-commit testing environment currently runs 'hardy', and
> that does not have python-sphinx available.
>
> We have a few of [easyish] options.
>   - don't make this change
>   - stop testing that the docs build

To clarify, right now we're testing that the Bazaar docs build using 
docutils. Given that our official docs have been built using Sphinx 0.6 
since Bazaar 2.0 (Sep 2009), the current "test" isn't overly valuable. 
Worse still, it is arguably giving us a false sense of security: Sphinx 
builders can fall over on ReST that docutils accepts in some isolated 
cases. :-(

I agree that we need to be validating that our docs build correctly 
under Sphinx. I'm not convinced though that we must do that as a 
pre-commit test *right now*. Some alternatives ...

Until our build environment upgrades to lucid, we could instead tap into 
the existing scripts we have that:

1. automatically rebuild doc.bazaar.canonical.com and the PDFs
2. build the Windows installers (including the Windows help)

and send email to various people if and when they fail. In that way, we 
only need to maintain the full doc toolchain for each target output 
format in the location where it is actually required.

Or we could test doc builds (html only say) on babune maybe?

> Anyhow, I don't have a particular course to recommend, and I think we
> need some discussion about this, which is why I've pulled it here from
> the merge proposal that Ian had put forward.

Agreed. Thanks for moving the discussion onto the list.

Ian C.