launchpad-dev team mailing list archive

[Stuart Bishop <stuart.bishop@xxxxxxxxxxxxx>]

On Thu, Oct 6, 2011 at 8:37 PM, Aaron Bentley <aaron@xxxxxxxxxxxxx> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> On 11-10-06 05:14 AM, Matthew Revell wrote:
>> Now, as for whether we favour Sphinx docs or doctests, I'm a
>> little less clear on. I prefer the Sphinx stuff because anyone can
>> access them via rtfd. However, my experience with doctests is
>> pretty limited.
>
> I think we should favour doctests, but we may be able to provide them
> through Sphinx.  I don't like calling them "doctests", because they
> should be testable documentation, rather than being focused on
> testing.  We should just call them documentation.

Manuel provides lots of nice stuff focused on testable documentation.
At a minimum, it provides a way to run your Sphinx documentation as
doctests, including test isolation and nicer formatting (hiding
setup/teardown or being able to dump the >>> for instance). I'd
suggest skimming through the features at
http://packages.python.org/manuel/

For testable documentation, I think raw Sphinx or doctests would
perpetuate problems we want to solve.
http://pypi.python.org/pypi/pytz/ is an example of Sphinx
documentation that is tested as doctest, and I think it would be
improved by the things Manuel offers.

-- 
Stuart Bishop <stuart@xxxxxxxxxxxxxxxx>
http://www.stuartbishop.net/