[Numpy-discussion] Topical documentation

Joe Harrington jh@physics.ucf....
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
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--


More information about the Numpy-discussion mailing list