[Numpy-discussion] [SciPy08] Documentation BoF
Pauli Virtanen
pav at iki.fi
Mon Aug 25 07:18:52 EDT 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 at 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