[Numpy-discussion] Topical documentation

Anne Archibald peridot.faceted@gmail....
Thu Jun 26 10:08:02 CDT 2008


2008/6/26 Stéfan van der Walt <stefan@sun.ac.za>:
> Hi all,
>
> We are busy writing several documents that address general NumPy
> topics, such as indexing, broadcasting, testing, etc.  I would like
> for those documents to be available inside of NumPy, so that they
> could be accessed as docstrings:
>
>>>> help(np.doc.indexing)
>
> or
>
> In [15]: np.doc.indexing?
>
> If I had to implement it right now, I'd probably
>
> - Have a directory full of topic.txt files.
> - Upon importing the doc sub-module, setup doc.topic and add docstring
> accordingly.
>
> Does anyone have comments or suggestions regarding such a framework?

I think making them available inside np.doc is a good idea. Should
np.doc.indexing contain anything but the single docstring?

It's also worth making some of the examples work as doctests, both to
get better testing - some of the indexing operations don't work, or at
least, don't do anything I can understand - and to keep the examples
in syn with the code. To make this happen, might it not be better to
create doc/indexing.py, containing
__doc__="""..."""?

The topical documentation would presumably also be ReST. Any further
conventions it should follow?

Anne


More information about the Numpy-discussion mailing list