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.
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.
+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
On Sun, Aug 24, 2008 at 15:05, Ondrej Certik <ondrej@certik.cz> wrote:
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.
We do some preprocessing, I believe.
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.
The idea of having a this_docstring_sucks() function was certainly bounced around at the BoF. :-) -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco
Mon, 25 Aug 2008 00:05:06 +0200, Ondrej Certik wrote:
On Fri, Aug 22, 2008 at 10:26 AM, Stéfan van der Walt <stefan@sun.ac.za> wrote: [clip]
- 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? [clip]
+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.
Sphinx offers enough hooks in autodoc for proper mangling of the docstrings, so the numpy format we have already agreed on can be used without problems. What we have now can be found here: https://code.launchpad.net/~pauli-virtanen/scipy/numpy-refguide https://code.launchpad.net/~stefanv/scipy/numpy-refguide Splitting the docstrings so that there's one docstring per page proved more difficult to do, especially if we want informative listings of the functions available. Currently our autosummary:: directive + automatically generated RST files can manage it, but it's not very elegant. Another question that pops up is how to integrate Travis's newly free Guide to Numpy to numpy documentation, as there is already some overlap with the docstrings and the reference part of the Guide. The main questions I see is that - What were the conclusions about this in the BoF and other discussions in Scipy'08? - Should we have a separate User manual and a Reference manual, or only a single manual? - What to do with the numpy.doc.* docstrings and Travis's book? There is obviously some overlap here. How to combine the material? - I vaguely remember someone mentioned having done numpybook -> RST conversion. If so, is the result somewhere available? Was something done towards this in the Scipy'08 sprints? I already wrote a rough LyX -> RST converter myself, but would like to avoid further duplication of work...
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.
Pointing the browser at %(BASEURL)s/doc/%(obj.__name__)s/ should do it. -- Pauli Virtanen
On Mon, Aug 25, 2008 at 4:18 AM, Pauli Virtanen <pav@iki.fi> wrote:
- I vaguely remember someone mentioned having done numpybook -> RST conversion. If so, is the result somewhere available? Was something done towards this in the Scipy'08 sprints?
Yes. Gabriel Gellner is working on this and is pretty far along. He is traveling at the moment, but should be checking something in later this week. Cheers, -- Jarrod Millman Computational Infrastructure for Research Labs 10 Giannini Hall, UC Berkeley phone: 510.643.4014 http://cirl.berkeley.edu/
Pauli Virtanen wrote:
- I vaguely remember someone mentioned having done numpybook -> RST conversion. If so, is the result somewhere available? Was something done towards this in the Scipy'08 sprints?
Yes, Gabriel Gellner made progress on this during the sprints, and I asked him to post his scripts for doing it. I don't have his email address currently, but perhaps he will respond. -Travis
Mon, 25 Aug 2008 11:18:52 +0000, Pauli Virtanen wrote: [clip]
https://code.launchpad.net/~pauli-virtanen/scipy/numpy-refguide
For coordination: I'm starting to add and Sphinxify relevant C-API reference documentation parts from Travis's book [1] (numpy/doc/numpybook/ capi.lyx) to the above "reference manual". Big thanks to Travis for making the book free! Good ideas what to do with the overlap in numpy.doc.* docstrings and the material in the book is also appreciated; I wasn't present in Scipy'08, so I'd be interested in hearing what kind of conclusions were reached there. I think it would also be great if some of the documentation in the book eventually hit the Numpy docstrings: I'd encourage everyone currently writing stuff in the Documentation Marathon to take a look at the book: the material describing functions etc. looks excellent for making good docstrings. .. [1] http://www.tramy.us/numpybook.pdf (Note that this PDF is apparently slightly old and still says the book is released only in 2010 and not in 2008 like the version in numpy SVN says). -- Pauli Virtanen
Tue, 26 Aug 2008 11:24:24 +0000, Pauli Virtanen wrote: [clip]
For coordination: I'm starting to add and Sphinxify relevant C-API reference documentation parts from Travis's book [1] (numpy/doc/numpybook/ capi.lyx) to the above "reference manual".
Ok, one Sphinxified capi.lyx is here: [1], using this converter [2]. But it required largish amounts of manual editing on top, so I'll leave numpybook.lyx for later or for other people to do -- there should be a way to do much of the cross-referencing & function annotation drudgework automatically. .. [1] http://www.elisanet.fi/ptvirtan/tmp/numpy-refguide/_sources/c-api/index.txt .. [2] http://www.elisanet.fi/ptvirtan/tmp/lyx2rst -- Pauli Virtanen
participants (6)
-
Jarrod Millman -
Ondrej Certik -
Pauli Virtanen -
Robert Kern -
Stéfan van der Walt -
Travis E. Oliphant