On Thu, Oct 6, 2011 at 8:37 PM, Aaron Bentley <aa...@canonical.com> 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 <stu...@stuartbishop.net> http://www.stuartbishop.net/ _______________________________________________ Mailing list: https://launchpad.net/~launchpad-dev Post to : launchpad-dev@lists.launchpad.net Unsubscribe : https://launchpad.net/~launchpad-dev More help : https://help.launchpad.net/ListHelp
