[SciPy-user] Documentation (Anne Archibald)

[jh at physics.ucf.edu]

Anne writes:

> It seems like it would be valuable to have such a description,
> but I'm not sure where it should go: duplicated in every one of
> scipy's spline-fitting functions? at the module level? in some
> automatic docstring transmogrifier that puts it in all relevant
> docstrings without requiring source code duplication?

First, thanks for researching and writing this!

This is going to become a general issue, particularly for scipy, where
there may be need for many of these in certain modules.  What we
choose for this one should scale to having many of these per
sub-module in some cases, and just one or none in others.  I would
think that the first one or two per sub-module could go in the
sub-module's docstring as you suggest, but after that we should
separate all of them into either a .doc sub-sub-module for that
sub-module (as now exists for numpy itself) or a function called
doc_splines (in this case) that contains only the docstring and
"pass".  Either way, those pages should be referenced in the
sub-module docstring so people know they exist.

If we do the doc-function, which is admittedly a hack but which may be
more convenient than having to do yet another import, the one-line
description should say something appropriate to identify it in lists
of functions, something like "documentation for spline
implementation".  If we could make np.info() import anything it needs
to in order to access the named docstring, it would make life easier
and the .doc sub-sub-module more attractive, since you wouldn't have
to import it.  In this case, np.info(sp.foo.doc.spline) would import
sp.foo.doc automatically.

Whatever is decided, a description should go in the doc standards.

--jh--