[Numpy-discussion] [SciPy08] Documentation BoF
Stéfan van der Walt
Fri Aug 22 03:26:13 CDT 2008
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?
- 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
- 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.
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.
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
json indices, or some other means.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Numpy-discussion