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