[SciPy-dev] FFT docstrings (was: Scipy Tutorial (and updating it))

jh@physics.uc... jh@physics.uc...
Sun Dec 14 13:34:06 CST 2008


> Pauli says:
> I'd think there are plenty of possibilities for plots in Numpy 
> documentation. For example, polyfit, etc. I'd also want to avoid putting 
> any file names to the docstrings, as the base directory for these is 
> ambiguous, and having a file name in the documentation is not really 
> helpful for the reader. Moreover, filenames may easily clash, eg. 
> plot-1.jpg, plot-2.jpg, etc.

Well, we've had this discussion before, last spring when we discussed
adding the "image" directive.  Some felt strongly that any sort of
image in the help() docs should be avoided since some people may be
reading in a text-only mode or may not have matplotlib installed
(e.g., OLPC users).

We could have decided to write slightly different docs for help() and
for the PDF/HTML version.  Sadly, we do not control help(): whatever
is in the docstring, directives and all, will be seen by the reader.
But, we agreed on the principle of keeping the docstrings as the
ultimate source of the reference docs, because a more removed source
that produced the docstring would be even less likely to be kept
updated by developers than docstrings, and we are very far behind on
even the docstrings.  So, putting a lot of images into our paper docs
means putting them in our help() docs as well, and the more that are
there the less happy text-only readers will be, particularly if the
images/plots are critical to the text.

Because matplotlib might not be available, we need to provide a copy
of the image or plot.  That requires a naming standard, and an obvious
one would be the full name of the object followed by -plot1.png,
-image1.png, etc.  We need to identify a directory in the release to
put these in (I think Stefan might have, already).  Then the help()
text gives the inclusion directive, the pathname for those using plain
help(), and (usually) the commands to make it, set as an example.

I will agree with those who say that help() text will be a little
cluttered.  But, given the constraints, we have the option not to
serve OLPC users and maybe get removed from their release, to avoid
images altogether, or to move to a higher-level source file that
produces a cleaner help() text, and convince the developers to update
that rather than ever touching the docstring.  I prefer living with a
little clutter, or mainly using the PDF or HTML versions, and I think
that was also how others were leaning last spring.

We need some regular input from some people who actually work in the
OLPC environment, or others for whom PDF/HTML don't work for some
reason, or who read only using help() for some reason other than
religion.  I'm defending their interests by applying theory rather
than actually knowing what they care about and can/can't tolerate.

> The help command can be overridden by replacing __builtin__.help, but I 
> don't think doing this kind of monkeypatching is the proper thing to do 
> on "import numpy".

I do not advocate monkeypatching help()!  That would have our help
reading other packages() docstrings.  Rather, I would feed back a
help() that looks for packagename.help() and calls that if it exists,
else just calls the current help().  We *could* monkeypatch that new
help() temporarily, but I'd rather leave that to the user's
discretion.

--jh--




More information about the Scipy-dev mailing list