[Numpy-discussion] Topical documentation
Thu Jun 26 10:08:02 CDT 2008
2008/6/26 Stéfan van der Walt <firstname.lastname@example.org>:
> 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:
> In : 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
> 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
The topical documentation would presumably also be ReST. Any further
conventions it should follow?
More information about the Numpy-discussion