[SciPy-dev] Scipy Tutorial (and updating it)
Thu Dec 4 16:45:04 CST 2008
Thu, 04 Dec 2008 16:23:36 -0500, josef.pktd wrote:
>> 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
> with sphinx rendered
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
> also I like the overview tables of functions and classes that you have
> in the editor
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
> 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.
> 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
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.
More information about the Scipy-dev