Doc rendering improvement suggestions.
Florent Hivert
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
> One thing that I dislike in the current doc rendering is that the method are
> reordered in alphabetical order.
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
wrote:
>
> 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 ?
> 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 ?
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
> 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
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
> > 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
> 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:
John H Palmieri
> 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.
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
> 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
> > > 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
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 :-)
Cheers,
Florent