On Wed, Mar 4, 2009 at 3:06 AM, Alan Gauld <alan.ga...@btinternet.com> wrote: > > "Carlos Daniel Ruvalcaba Valenzuela" <clsdan...@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 _______________________________________________ Tutor maillist - Tutor@python.org http://mail.python.org/mailman/listinfo/tutor
