Hi David,
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
--
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
