Hi there,
Here are some random suggestion about sphinx doc rendering.
Disclaimer: I've no idea how much these are doable in sphinx.
One thing that I dislike in the current doc rendering is that the method are
reordered in alphabetical order. It's good for reference but usually in the
source files methods are grouped in a meaningful order which may be better to
be kept. I'd rather have the methods listed in the order they are written in
the file toghether with some alphabetically ordered table of content (see next
paragraph). As far as I understand sphinx get the doc by introspection, so
that the order in the file is completely lost. Is this true ? Can there be a
way to achieve this nevertheless ?
Some files and classes are pretty big and will even grow more. I'm thinking in
particular about the file for permutations in combinatorics, but that not the
only case:
tomahawk-*at/sage/combinat $ grep def permutation.py | grep -v __ | wc
148 426 5244
Is it possible to automatically generate a table of content/summary (lists of
documented things) at the end of the files with the relevant links ?
With the help of inheritance, many class have a lot more methods that appear
in the doc. However, I can't find any information about inheritance in the
current sphinx rendering, is there one ? I think there should be a way in the
refman to get this information. Of course, it would be better to do this
automatically for consistency. I can think of to ways: when documenting a
class, either put systematically links to the upper classes, or else put some
array with inherited methods together with links. It could be particularly
useful for example for matrices where methods are dispatched into several
files without any particular meaningful name (matrix0.py, matrix1.py...)
Unfortunately, even if we agree on some layout, I'm not sure I can to this by
myself. I'm rather incompetent in sphinx, though I'd like to learn.
Cheers,
Florent
--~--~---------~--~----~------------~-------~--~----~
To post to this group, send an email to sage-devel@googlegroups.com
To unsubscribe from this group, send an email to
sage-devel-unsubscr...@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sage-devel
URL: http://www.sagemath.org
-~----------~----~----~----~------~----~------~--~---
