[Numpy-discussion] Topical documentation
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? Thanks for your time, Stéfan ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Topical documentation
2008/6/26 Stéfan van der Walt [EMAIL PROTECTED]: 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 ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Topical documentation
Just to clarify, the documentation Stefan refers to is topical *reference* documentation for the numpy package infrastructure, conventions, etc. The contemplated .doc module will be a few kB of distilled reference text. Its contents will be included in the PDF and HTML reference guides. It may include such topics as: summary of numpy package capabilities and conventions includes a list of these topics and related docstrings elsewhere, like np.ndarray.__doc__ indexing and slicing broadcasting list of functions by topic essential performance hints (i.e., don't loop, not how to write parallel C extensions) etc. Brief words on how to use the documentation will become part of numpy.__doc__. We're not contemplating turning tutorial documentation (cookbook recipes, user guide, discipline-specific stuff) into numpy objects. ReST formatting conventions will be identical to that for docstrings, since these will be docstrings. Doctests need to work, of course. Given that there will be a small number of these topics (fewer than 20, perhaps fewer than 10), should they be imported into the top level on numpy load? That would allow the more intuitive help(np.indexing) We should only say yes to this question if they will load on every import of numpy. I would not want them to land in the main level only after importing the doc module. --jh-- ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
