[Numpy-discussion] Topical documentation
Thu Jun 26 11:26:51 CDT 2008
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
list of functions by topic
essential performance hints (i.e., "don't loop", not "how to write
parallel C extensions")
Brief words on how to use the documentation will become part of
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
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.
More information about the Numpy-discussion