Doc rendering improvement suggestions.

1 view
Skip to first unread message

Florent Hivert

unread,
Nov 13, 2009, 3:39:53 AM11/13/09
to Sage Devel
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

slabbe

unread,
Nov 13, 2009, 6:07:50 AM11/13/09
to sage-devel
Hi Florent,

> One thing that I dislike in the current doc rendering is that the method are
> reordered in alphabetical order.

I remember I read this question in sage-devel last summer and I just
found the link :

http://groups.google.com/group/sage-devel/browse_thread/thread/ebbf7ebe8ebad570/3b7e0aa6906a0509?hl=en&lnk=gst&q=order+sphinx+group%3Asage-devel#3b7e0aa6906a0509

And I also found this one about other sphinx documentation issues :

http://groups.google.com/group/sage-devel/browse_thread/thread/80a99dc2c2836a7b/ad3407f7714349bf?hl=en&q=sphinx+group:+sage-devel#ad3407f7714349bf

Sébastien

John H Palmieri

unread,
Nov 13, 2009, 3:24:06 PM11/13/09
to sage-devel
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:

Chain complexes
===============

.. This file has been autogenerated.

.. automodule:: sage.homology.chain_complex
:members:
:undoc-members:

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

automodule = '.. automodule:: %s\n :members:\n :undoc-
members:\n\n'

to

automodule = '.. automodule:: %s\n :members:\n :undoc-
members:\n :inherited-members:\n\n'

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

Jason Grout

unread,
Nov 13, 2009, 6:15:29 PM11/13/09
to sage-...@googlegroups.com
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.

Jason

William Stein

unread,
Nov 13, 2009, 6:25:24 PM11/13/09
to sage-...@googlegroups.com

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

Florent Hivert

unread,
Nov 13, 2009, 7:58:46 PM11/13/09
to sage-...@googlegroups.com
Hi,

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

Pat LeSmithe

unread,
Nov 13, 2009, 8:36:11 PM11/13/09
to sage-...@googlegroups.com
On 11/13/2009 04:58 PM, Florent Hivert wrote:
> 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."

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:

http://groups.google.com/group/sage-devel/browse_thread/thread/a34a80097ad47805/2e57eb60d7f9881d?#2e57eb60d7f9881d

John H Palmieri

unread,
Nov 14, 2009, 12:42:38 AM11/14/09
to sage-devel
On Nov 13, 5:36 pm, Pat LeSmithe <qed...@gmail.com> wrote:
> On 11/13/2009 04:58 PM, Florent Hivert wrote:
>
> > 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."
>
> 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.

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

John

Pat LeSmithe

unread,
Nov 14, 2009, 2:44:47 AM11/14/09
to sage-...@googlegroups.com
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

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?

Nicolas M. Thiery

unread,
Nov 14, 2009, 4:13:59 AM11/14/09
to sage-...@googlegroups.com
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.

> \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/

Florent Hivert

unread,
Nov 17, 2009, 6:02:27 PM11/17/09
to sage-...@googlegroups.com
Hi there,

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 :-)
Alas not Yet !

Cheers,

Florent
Reply all
Reply to author
Forward
0 new messages