[Numpy-discussion] [SciPy08] Documentation BoF

Ondrej Certik ondrej@certik...
Sun Aug 24 17:05:06 CDT 2008

On Fri, Aug 22, 2008 at 10:26 AM, Stéfan van der Walt <stefan@sun.ac.za> wrote:
> Hi all,
> This is my personal recollection of the documentation BoF.  Feel free to
> comment or correct the text below.
> Regards
> Stéfan
> Summary of the Documentation Birds-of-a-Feather Session
> =======================================================
> Topics proposed for discussion
> ------------------------------
> - Path towards getting SciPy documented using the online documentation
> editor
> - Intersphinx: linking Sphinx-using projects
> - Culture / methodology: what do we expect from code accepted into
> NumPy/SciPy?
> - 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.


Currently sphinx can't handle scipy docstrings, can it? It didn't for
me at least. It'd be nice if whatever format you agre upon, could work
with sphinx's autodoc.

Also I am very interested in your web based editing of docstrings, so
that people can just fix and improve the docstrings easily. I can
imagine something like

In [1]: e.series???

in ipython and it would fireup a browser pointing to the docstring and
one would just fix it. Since you did most of the work already, maybe
the above won't be that hard to do either.


More information about the Numpy-discussion mailing list