[Numpy-discussion] [SciPy08] Documentation BoF

[Ondrej Certik]

On Fri, Aug 22, 2008 at 10:26 AM, Stéfan van der Walt <stefan at 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.


+1

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.

Ondrej