[SciPy-dev] Of use and abuse of sphinx's math directive

jh@physics.uc... jh@physics.uc...
Wed Oct 29 12:23:51 CDT 2008


"David Cournapeau" <cournape@gmail.com>:

> I am not sure the comparison is accurate: docstrings are not meant to
> be edition-ready. They are meant to be read from the interpreter
> mainly; for help meant to be put in a general documentation, I think
> separate doc is better, and there you can go crazy about  latex and
> co.

At the start of the doc marathon, we considered having an ueberdoc
that produced the text docstrings and the PDF and HTML manuals, but
decided that developers would be most likely to update docs if they
were the docstrings and not some separate set of files.  We knew this
would result in some formatting imperfections, but decided to favor
content over form.  We have one doc source, the docstrings.  Even the
general-interest docs (slicing, glossary, etc.) are docstrings.

E unum pluribus, I guess.

--jh--


More information about the Scipy-dev mailing list