[Tutor] Code documentation

[Kent Johnson]

On Wed, Mar 4, 2009 at 3:06 AM, Alan Gauld <alan.gauld at btinternet.com> wrote:
>
> "Carlos Daniel Ruvalcaba Valenzuela" <clsdaniel at gmail.com> wrote
>
>> which approach should I take on documentation (API docs) for a python
>> library I have been working on, there is currently code docstrings,
>
> docstrings are the minimum since they show up on help()
>
>> docstrings with some markup (epydoc, etc), or external programs such
>> as Sphinx (reStructuredText markup).

epydoc is good for creating a bare-bones API document. It gives a
high-level view with links around the code and, optionally, to the
source. Its usefulness depends a lot on how good your doc strings are.
It can work with plain doc strings or you can mark them up to make a
richer API document at the expense of less readable help() text.

Sphinx seems to be the tool of choice for creating narrative docs for
Python projects. It is probably a good choice if you want to write
more than just doc strings.

> Personally I never use these. I use help() in the first instance and
> failing that go to the html module docs.

The Python html module docs are generated with Sphinx since 2.6.

Kent