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