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

[Pauli Virtanen]

Thu, 04 Dec 2008 16:23:36 -0500, josef.pktd wrote:
[clip]
>> 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

The font size in the Sphinx docs is indeed a bit large: it's the 
browser's default size which may vary across browsers. This should 
probably be fixed.

I'd believe the line spacing is the same for both, but it scales with 
font size.

> 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

The summary listings try to accomplish this.

> 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.

It can be made to stay in the screen, but this requires some more serious 
CSS wizardry.

> 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?

In my opinion the documentation should go only in one of these two, and 
the other should be nearly empty. If it goes to info.py, then the 
corresponding rst file should only contain an automodule:: directive. 

The only reason why documentation couldn't go to info.py is that a part 
of the numpy-specific machinery doesn't handle the autosummary:: 
directives properly in docstrings.

Before the fix, I'd guess it's best to concentrate on the .rst docs. We 
can easily copy and paste the whole file contents to info.py, if we 
decide to change this.

[clip]
> 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

Hmm yes. There's no programmatic way of determining that __doc__ comes 
actually from info.py, apart from AST parsing. I'll have to think about 
whether to rewrite the docstring extraction code.

-- 
Pauli Virtanen