Hi there,
I'm writing here about Ticket #9128 "Sphinx should be aware of all.py to find
its links". The purpose of this ticket is to teach sphinx how to look into
"sage.all" to resolve dangling hyperlinks. So for example, instead of writing:
:meth:`Algebras.ParentMethods.algebra_generators()
<sage.categories.algebras.Algebras.ParentMethods.algebra_generators>`.
I would be very happy if I can write only
:meth:`Algebras.ParentMethods.algebra_generators`
I proposed a first solution 21 months ago, various bugs and problems were
corrected and several users seems to be happy with my patch. It seems that
there is a consensus among the people aware of that ticket to have it enter
Sage. The main problem is that none of the people playing with it (including
me !) have the necessary expertise to check if everything is correct. As
anyone can see from the code, I wrote my patch using log backtrace and
{{{pdb}}}. At several point, I'm using call to sphinx or docutils internals
which are not really documented. So this is some kind of reverse engineering
working around seemingly bugs. I tried several time to ask for some help on
sphinx-user mailing list and never got any answer on that. At the end I'm not
following this list anymore. My diagnostic is that Sphinx doesn't expose a
sufficiently flexible API to achieve what we want.
Probably a good solution would be to have a Sage-days whose subject is Sphinx
and doc-compiling and invite George Brandl (the author of Sphinx). We could
also solve the Sphinx parallel build ticket (#6495 Build the reference manual
incrementally) at the same occasion. Unfortunately, I just organized a
Sage-days and I'm invited to two other until summer so I won't organize such a
days in a short future and if someone organized it, I won't probably able to
attend.
In the mean time, my opinion is that the feature is important enough to let it
enter Sage in its current state, maybe with some minor correction. I would
like to know if this opinion is widely shared among Sage users.
Cheers,
Florent
--
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
