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.
On Nov 13, 12:39 am, Florent Hivert <florent.hiv...@univ-rouen.fr>
wrote:
> 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 ?
I'm not sure about this one.
> 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 ?
Currently, we automatically generate files like SAGE_ROOT/devel/sage/
doc/en/reference/sage/homology/chain_complex.rst, which looks like
this:
If we add a line ":inherited-members:" at the bottom, then the
inherited methods should show up. We can do this everywhere by
modifying SAGE_ROOT/devel/sage/doc/common/builder.py: change line 578
from
You can test this out by building the reference manual, then making
this change in builder.py, then touching just one or two Sage library
files. When you run "sage -b" and rebuild the manual, only the pages
for those files should change, so you can see the difference.
This will result in a lot of repetition in the reference manual, of
course.
John H Palmieri wrote: > 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.
>> 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.
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.
> > 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 :-)
> 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."
> > 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."
Right: if you do this, the reference manual for chain complexes looks
like:
class sage.homology.chain_complex.ChainComplex(data=None, ...)
Bases: sage.structure.sage_object.SageObject
and in the "Bases" line, you can click on "sage.structure...." to go
to the relevant documentation.
I like this. (Note, though, that it doesn't show all of the methods
for chain complexes (for instance) in one place, and it doesn't let
you easily see which ones from SageObject may have been overridden.)
> I like this. (Note, though, that it doesn't show all of the methods > for chain complexes (for instance) in one place, and it doesn't let > you easily see which ones from SageObject may have been overridden.)
On including inherited members but not their docstrings: Can we detect them and "zero" their docstrings in autodoc-process-docstring
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. * ???
On Sat, Nov 14, 2009 at 01:58:46AM +0100, Florent hivert wrote: > > > 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
+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.
> 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}>
I really like to see the following questions answered and the answer
implemented in sage. There has been already at least 5 or 6 discussion on
sage-devel about improving the doc... few of them are conclusive. I think we
should push this discussion to its end...
Though I'm far from being a sphinx expert, I'm also volunteering for help as
soon as we decide what we want and someone give me a pointer on some doc on
how to do it. I ow at this this after the criticisms about the doc I've
written of sage-devel :-)
> On 11/13/2009 09:42 PM, John H Palmieri wrote:
> > I like this. (Note, though, that it doesn't show all of the methods
> > for chain complexes (for instance) in one place, and it doesn't let
> > you easily see which ones from SageObject may have been overridden.)
> On including inherited members but not their docstrings: Can we detect
> them and "zero" their docstrings in autodoc-process-docstring
> 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.
> * ???
