Sphinx related ticket #9128
Florent Hivert
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
Dr. David Kirkby
> 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.
<snip>
> 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
It does seem a good idea to me to put code which you freely admit is using
undocumented features which you don't really understand well.
I'm basing that on a general principle, rather than gathered through a deep
knowledge of what you are doing.
I think you other idea of trying to get some experts involved would be more
useful. It's a shame the Sphinix list is not more helpful. Some lists are very
good (sage, mpir, autoconf), some are medicore and some like R, are pretty
offensive some times.
Florent Hivert
On Sat, Feb 18, 2012 at 10:40:43PM +0000, Dr. David Kirkby wrote:
> On 02/18/12 06:54 PM, Florent Hivert wrote:
> >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.
>
> <snip>
>
> >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.
>
> It does seem a good idea to me to put code which you freely admit is
> using undocumented features which you don't really understand well.
Do you mean "It doesn't seem a good idea" ? I completely agree with
that. However, I think in this case this is quite harmless for the
following reasons:
- The feature I'm adding (resolving links in the doc) is completely
orthogonal to any other feature in Sage. It won't break any calculation,
nothing will rely on it except having a better documentation.
- If a better solution is found, we will have nothing to change in the code
except Sphinx configuration (sage/common/conf.py).
- If it breaks in a future release of Sphinx, it will be trivial to
deactivate and remove. I can even trivially make it an optional feature
controlled by a shell variable.
- If the feature is removed because it breaks at some point, using my patch I
can easily get a log of all links being resolved, which could possibly be used
in a script fixing automatically the source. I will strongly vote against this
for reasons already discussed on this mailing list (rebasing hell).
That why I find it reasonable to let this code go into Sage.
Cheers,
Florent