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? 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 -~----------~----~----~----~------~----~------~--~---
