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
> This will result in a lot of repetition in the reference manual, of
> course.
As an online document, I think the cost for repetition is almost
nothing, and is greatly outweighed by the benefit of having these
inherited functions explicitly listed.
Jason
We can also *list* them without listing their docstrings. I.e., a
list (with links) to the docs of the functions in the base classes,
but don't actually give the whole docstring again.
William
> > As an online document, I think the cost for repetition is almost
> > nothing, and is greatly outweighed by the benefit of having these
> > inherited functions explicitly listed.
>
> We can also *list* them without listing their docstrings. I.e., a
> list (with links) to the docs of the functions in the base classes,
> but don't actually give the whole docstring again.
+1
If it's doable, I think that is the good way, as I suggested:
> when documenting a class, either put systematically links to the upper
> classes, or else put some array with inherited methods together with
> links."
This will become even more crucial with the entering of categories whose goal
is precisely to let inheritance gather a lot of code.
\begin{Advertising}>
As a demo and advertising, I like the following code which is a real example a
a research problem I'm working on with Nicolas and Anne Schilling:
class NDPFMonoid(AutomaticMonoid):
def __init__(self, n):
ambient_monoid = DiscreteFunctions(range(1,n+1), action="right")
pi = Family(range(1, n),
lambda j: ambient_monoid(dict(
[(i, i) for i in range(1,n+1) if i != j+1]+[(j+1,j)])))
AutomaticMonoid.__init__(self, pi, one = ambient_monoid.one(),
category = (SubFiniteMonoidsOfFunctions(),
FiniteJTrivialMonoids()))
The goal is to define the monoid of nondecreasing function from [1..n] to
itself such that f(i) <= i... That's it. Everything else is inherited from the
construction of the element and the product rule to the computation of the
representation theory... And every single piece of information here is of
mathematical nature: I define it as generated by the functions
pi_j : j+1 -> j
: i -> i if i <> j+1.
The necessary code is in on its route to sage :-)
\end{Advertising}>
Cheers,
Florent
According to
http://sphinx.pocoo.org/ext/autodoc.html
we can use, e.g.,
.. automodule:: sage.algebras.steenrod_algebra
:members:
:undoc-members:
:show-inheritance:
to leave a trail of superclasses.
Perhaps we can use the autosummary extension
http://sphinx.pocoo.org/ext/autosummary.html
in some way for the other problems?
Also of potential use is the inheritance diagram extension:
http://sphinx.pocoo.org/ext/inheritance.html
There's a sample patch at
http://trac.sagemath.org/sage_trac/attachment/ticket/6586/inheritance_example.patch
Unfortunately, it's not automatic.
A link to this thread:
On including inherited members but not their docstrings: Can we detect
them and "zero" their docstrings in autodoc-process-docstring
http://sphinx.pocoo.org/ext/autodoc.html#docstring-preprocessing
?
On a related note: Should we include [documented] hidden methods (e.g.,
__init__)? Can we do this with autodoc-skip-member
http://sphinx.pocoo.org/ext/autodoc.html#skipping-members
?
On another note: For single-page transformations, it may be easier or
otherwise worthwhile to add JavaScript code to layout.html that, e.g.,
* Adds sidebar links for each class.
* Collects all classes, functions, and methods at the bottom of the page.
* Toggles (hide/show) the display of all docstrings.
* ???
Does the documentation include nested classes?
+1
> > when documenting a class, either put systematically links to the
> > upper classes, or else put some array with inherited methods
> > together with links."
>
> This will become even more crucial with the entering of categories
> whose goal is precisely to let inheritance gather a lot of code.
One extra technicality with categories is that the inheritance is
resolved at runtime. So making this fully work would require sphinx to
do introspection not only on the class, but on an_instance() of the
class. I don't know if sphinx has some hooks for supporting this.
> \begin{Advertising}>
>
> As a demo and advertising, I like the following code which is a real example a
> a research problem I'm working on with Nicolas and Anne Schilling:
>
>
> class NDPFMonoid(AutomaticMonoid):
> def __init__(self, n):
> ambient_monoid = DiscreteFunctions(range(1,n+1), action="right")
> pi = Family(range(1, n),
> lambda j: ambient_monoid(dict(
> [(i, i) for i in range(1,n+1) if i != j+1]+[(j+1,j)])))
> AutomaticMonoid.__init__(self, pi, one = ambient_monoid.one(),
> category = (SubFiniteMonoidsOfFunctions(),
> FiniteJTrivialMonoids()))
>
> The goal is to define the monoid of nondecreasing function from [1..n] to
> itself such that f(i) <= i... That's it. Everything else is inherited from the
> construction of the element and the product rule to the computation of the
> representation theory... And every single piece of information here is of
> mathematical nature: I define it as generated by the functions
> pi_j : j+1 -> j
> : i -> i if i <> j+1.
> The necessary code is in on its route to sage :-)
> \end{Advertising}>
:-)
Cheers,
Nicolas
--
Nicolas M. Thiéry "Isil" <nth...@users.sf.net>
http://Nicolas.Thiery.name/