[Numpy-discussion] [SciPy08] Documentation BoF

Pauli Virtanen pav@iki...
Mon Aug 25 06:18:52 CDT 2008


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



More information about the Numpy-discussion mailing list