On Sat, Nov 14, 2009 at 02:20:43PM -0800, John H Palmieri wrote:
>
>
> In what way are they a total mess? I'm curious.
>
> > Of course, it was inevitable that we would run head first into this
> > problem eventually, and it's amusing that we did this week.
> >
> > Anyway, I agree with Robert -- to solve this particular problem we
> > will have to go creatively beyond what Sphinx offers "out of the box".
>
> Which particular problem? Alex just pointed out that we haven't been
> using standard Sphinx/reST for citations, and we should. That's easy
> to solve "in the box".
>
Here's an example (I'm not picking on you, John, this was just the
first instance I ran into this after doing search_src("REFERENCE") to
look for un-Sphinx-ified references.)
In the module docstring of steenrod_algebra.py, there is a reference
to Milnor's Annals paper [Mil]. I eagerly put this in proper Sphinx
syntax. Moving on to steenrod_algebra_element.py, I had to remove the
same reference from the module docstring because Sphinx complained.
So you can have something like "see [Mil]_" but then the actual
reference is nowhere to be found in that file.
This means that someone reading only this docstring does not have this
information at hand any more. Then we get to
steenrod_algebra_bases.py, where the Monks and Wood papers are now [M]
and [W], whereas in steenrod_algebra_element.py they were [Mon] and
[Woo]. Sphinxify these and you get duplicate references
with different names and labels.
Once again, I'm not picking on you or anybody else. But I think this
shows that it's hard to keep consistency alive even in cases where a
single author wrote a bunch of files, never mind what happens when ten
different people work on the same code. It adds to the author's
workload and to the reviewer's workload. And as we pointed out
already, it cripples docstrings introspection.
Best,
Alex
--
Alex Ghitza -- Lecturer in Mathematics -- The University of Melbourne
-- Australia -- http://www.ms.unimelb.edu.au/~aghitza/
--~--~---------~--~----~------------~-------~--~----~
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
-~----------~----~----~----~------~----~------~--~---
