On Fri, Nov 13, 2009 at 11:18 PM, Robert Bradshaw <rober...@math.washington.edu> wrote: > > On Nov 13, 2009, at 9:53 PM, Alex Ghitza wrote: > >> Hi, >> >> Martin Albrecht pointed out to me that there is a way to markup >> citations and references in ReST (and that I should be using that in >> my patches). I was so happy to see this that I immediately fixed my >> patch and added a few words to the developer guide to this effect (see >> http://trac.sagemath.org/sage_trac/ticket/7456 for this). >> >> It would seem that it's a fairly simple habit to get into: instead of >> >> def do_this(): >> """ >> Return really great thing, based on [ABC]. >> >> REFERENCES: >> >> - [ABC] The ABC of great things >> >> """ >> >> you would write >> >> def do_this(): >> """ >> Return really great thing, based on [ABC]_. >> >> REFERENCES: >> >> .. [ABC] The ABC of great things >> >> """ >> >> However, there are some issues in doing this on the large scale that >> is the Sage library. >> >> 1. These references used to be local to the docstring they appear in. >> As soon as we ReST-ify them, they become global in the reference >> manual. Therefore if there is already a reference labeled [ABC], >> Sphinx will rightfully complain. That's easy to fix, just use a >> different label. >> >> 2. What happens if we cite the same reference from two different >> docstrings? We have to pick which one docstring will contain the >> "definition" of the reference, otherwise Sphinx will complain about >> duplicates. The effect of this is: >> >> a) in the html output, the citation itself is a link to the reference, >> so it's easy to get to it >> >> b) in the pdf output, all the references are *only* listed in the >> bibliography section toward the end of the document. This means that >> there are a bunch of lines that just say "REFERENCES" and nothing else >> in the docstrings. Not very useful or pretty, so it would be great if >> we could somehow remove them. >> >> c) in the docstring itself (obtained by introspection or by reading >> the code directly), the citation will be there saying "see [ABC]" but >> the actual reference could be nontrivial to find. In fact, the only >> way to find it that's sure to work is to do search_src(".. [ABC]"), >> because the definition could be in a different file, for instance. >> >> >> I'm not sure I like c), but maybe that's the price that we have to pay >> for having beautiful and consistent-looking documentation? > > This is one of the many, many cases where I think it would be easier > to fix the tool rather than change people's behavior. Why not have our > cake and eat it too? [ABC] can automatically be turned into [ABC]_ > (perhaps only if it matches something below). Global name conflicts > can automatically be resolved, either by picking the first (if they're > "close enough") or making them unique. The REFERENCES section can be > stripped if its empty. > > I reallly like ReST, and it's a huge step ahead of what we used to > have, but (and I've said this before) in many ways using raw ReST > seems like a step backwards (double ::'s for doctests, ` for math > mode, double-spacing function argument specs, etc.) > > - Robert
I strongly agree with this. In fact, last week when I was hanging out with Jarrod Millman (of scipy/numpy), he baited me -- "so, are you guys using Sphinx a lot for Sage yet?" When I said "yes!", he responded, "so how did you guys solve the references problem, since references are a total mess in Sphinx?" And said that we hadn't yet. 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". William --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
