On Fri, Aug 22, 2008 at 10:26 AM, Stéfan van der Walt <[EMAIL PROTECTED]> 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 _______________________________________________ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
