[Numpy-discussion] [SciPy08] Documentation BoF

Stéfan van der Walt stefan@sun.ac...
Fri Aug 22 03:26:13 CDT 2008

Hi all,

This is my personal recollection of the documentation BoF.  Feel free to
comment or correct the text below.


Summary of the Documentation Birds-of-a-Feather Session

Topics proposed for discussion

- Path towards getting SciPy documented using the online documentation
- Intersphinx: linking Sphinx-using projects
- Culture / methodology: what do we expect from code accepted into
- Tools for reading documentation (Help 2.0)
- The complete SciPy book -- how to get there
- NumPy Documentation Standard: is it useful beyond NumPy?

Conclusions reached

Documentation format
- Question: could we standardise the descriptions of data-types between docs
of different projects?  They should overlap to some extent.

- If we could agree on some common standard (or at least a common subset of
a format) across projects, IPython could parse and display docstrings with
special markup.

- Matplotlib should be involved in this conversation.  They have already
written a vast amount of documentation, and their needs may be different to
those of the SciPy projects.

Formal requirements
For functions going into NumPy and SciPy, we have a certain minimum
documentation requirements.  However, we'd rather take a somewhat liberal,
open approach, and accept code with somwhat inferior docstrings, working
with the author to improve them.  This way, we remain accessible as a
community, while striving to improve the quality of the code base.

Marketing SciPy
The current entry point for SciPy on the web (http://www.scipy.org) may be
confusing to beginners.  The web page should be redesigned, in a similar
fashion as the new Sage and code.enthought.com pages, linking to the messy
wiki behind it in a consistent fashion.  Joe Harrington may be able to hire
someone to work on this important aspect of SciPy marketing.

Cross-project documentation searching
Ideally, one should be able to perform a documentation search across several
projects.  In order to achieve this, we should negotiate a common convention
for installing Sphinx-generated documentation into a standard location.  A
javascript-backed webpage can then be provided to do a search, using the
json indices, or some other means.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://projects.scipy.org/pipermail/numpy-discussion/attachments/20080822/90261917/attachment.html 

More information about the Numpy-discussion mailing list