[SciPy-dev] ANN: NumPy/SciPy Documentation Marathon 2008
Sun May 18 20:10:56 CDT 2008
I'm excited that so many talented people are signing up to contribute to
the docs! Now I'm wishing that I had turned my debate with Stefan about
the number who would play into a bet for ice cream...ah well.
A quick comment about getting started. Please do read the front page of
the wiki and the docs it refers to. We spent considerable time
fine-tuning these to respond to exactly the questions that have been
raised regarding import format, how to sign up, ReST conventions, etc.
I'll provide rationale for some of these below.
1. I signed up on the wiki but can't edit; why?
Post your name and wait a day. We're trying to avoid wiki spam by
having the wiki chieftains approve editors by adding them to
EditorGroup. We don't have huge resources so we're trying to pre-empt
management problems like cleaning up wiki spam. Then we can spend more
of our limited time writing docs.
2. Workflow? How do I know what to edit, review, or proof?
We also don't have a workflow yet, though we have a utilitarian hack in
mind that should show the status of each function. Right now they're
all in need of editing, so we have a few weeks. Part of the problem is
that the wiki gets torn down and rebuilt every time Stefan checks the
docs in, and it's not a full web ap. If you have interest in helping
solve this problem *and you have no interest in writing*, please let us
know. Otherwise, please write, write, write! We have like 1000 proofed
pages to produce, maybe more.
3. import convention?
>>> 1) Assume 'from numpy import *'
>>> 2) Assume 'import numpy'??????
>>> 3) Assume 'import numpy as np'
For consistency in the docs, and likely to make doctests work, we need
to have just one set of assumptions for imports. It will confuse new
users and look very unprofessional if one docstring assumes "import
numpy", another "import numpy as np", another "from numpy import
thefunctionbeingdocumented" and so forth. We want to be clear and to
make the examples cut-and-pasteable for as many people as possible.
This is why we have asked people (in the doc instructions and example)
to assume "import numpy" for numpy docs, to assume that and "import
scipy" for scipy docs, and to make all other imports explicitly in the
examples (e.g., if you want to plot in an example).
We can discuss alternatives here, but we saw recently a variety of
opinion (my own perhaps too loudly expressed) on how best to abbreviate,
so I think that we'll probably end up in a religious war about how we
want to tell people to import. Since it should always be ok simply to
"import numpy", and since that is the simplest form of the import
command, my personal take is that this is the appropriate assumption to
make in the docs. The "assume import numpy" convention is at the very
least understood by all, as you have to do it to access the package.
My second preference, which looks more like other programming languages
and is briefest, is to assume the user has done "from whatever import
foo" on every function in the example. Sadly, this looks suspiciously
like "from whatever import *", and we definitely don't want to encourage
that practice. It's also not likely to be true. I'm still debating
with myself over whether we should put that explicit import at the start
of each example. It's an extra line, but it makes for the clearest and
briefest rest of the example, which is the interesting part. (Allow me
to show my silly side by saying that I usually lose these debates with
myself...by not deciding.)
More information about the Scipy-dev