[SciPy-dev] Scipy Tutorial (and updating it)

[josef.pktd at gmail.com]

>>
>> I like the new Sphinx docs a lot if I have to look up a specific topic,
>> but when I don't know which function might be useful for my case, then
>> the overview and speed of looking around is pretty tedious, compared to
>> the windows help files for matlab or R. (As an aside: I actually like
>> the style sheet of the documentation editor better than sphinx.)
>
> Can you be more specific: which elements of the page would you like to
> see changed?

This might be mostly a taste question, I don't like the font size and
line spacing in sphinx css. I find smaller fonts and smaller line
spacing much easier to follow and much faster to skim for relevant
parts.

compare
http://docs.scipy.org/scipy/docs/scipy-docs/stats.rst/#stats

with sphinx rendered
http://docs.scipy.org/doc/scipy/reference/stats.html

also I like the overview tables of functions and classes that you have
in the editor
http://docs.scipy.org/scipy/docs/scipy.stats/#scipy-stats

As I mentioned I really like the windows help file format, with
search, tree and lists on the left navigation pane, together with the
"see also" it is very fast to check out different related functions.
In the stats front page, which is pretty long the toc tree on the left
does not have enough depth for navigation around.

A question to the new docs: what's the relationship between the front
rst page and the info.py of a sub package, the two files above, both
have currently roughly the same content. Should it stay that way or do
they have different purpose?

One problem for editing the doc string, I found:
stats.info.py is rendered here
http://docs.scipy.org/scipy/docs/scipy.stats/#scipy-stats
put clicking on source, leads to  __init__.py instead of info.py
http://docs.scipy.org/scipy/source/scipy/dist/lib64/python2.4/site-packages/scipy/stats/__init__.py#0


I will have to sign up for editing, since immediate feedback on rst
errors, is much better than only editing the source without feedback,
for example http://docs.scipy.org/scipy/docs/scipy.stats.stats.kstest/

Thanks,

Josef