[Biopython-dev] Documentation

[Vince S. Buffalo]

I dug into how Numpy is processing their own ReST dialect, and the answer
lies in doc/HOWTO_BUILD_DOCS.txt. There is an extension that can be obtained
from PyPi, or included manually in a doc/sphinxext directory.

Are these extension requirements alright (before I continue changing the
format)? Some more information is below.


*Numpy's documentation uses several custom extensions to Sphinx.  These*
*are shipped in the ``sphinxext/`` directory, and are automatically*
*enabled when building Numpy's documentation.*
*
*
*However, if you want to make use of these extensions in third-party*
*projects, they are available on PyPi_ as the numpydoc_ package, and*
*can be installed with::*
*
*
*    easy_install numpydoc*
*
*
*In addition, you will need to add::*
*
*
*    extensions = ['numpydoc']*



On Thu, Jul 15, 2010 at 8:38 AM, Peter <biopython at maubp.freeserve.co.uk>wrote:

> On Thu, Jul 15, 2010 at 4:22 PM, Vince S. Buffalo <vsbuffalo at gmail.com>
> wrote:
> >>
> >>  I think the docstrings should be the primary API documentation,
> >>  and the Tutorial the primary introductory text.
> >
> > I like the idea of code and documentation living together, but one thing
> > that concerns me is that as the documentation grows larger and filled
> with
> > more examples, it may begin to clutter the code quite a bit.
>
> We can cross that bridge if we come to it - right now I would say most
> modules really need more docstrings. If you think that any of the
> docstrings
> you've looked at are too long, we can discuss shortening them (ideally by
> relocating good content or tests).
>
> Peter
>



-- 
Vince Buffalo
Programmer
Bioinformatics Core
UC Davis Genome Center
University of California, Davis

"There's real poetry in the real world. Science is the poetry of reality."
-Richard Dawkins