On Nov 14, 2009, at 2:36 AM, Florent Hivert wrote: > > Hi, > >> 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: > > [...] > > One good habits which will probably solve a large part of the > duplicate it to > put the reference not in the doctring of the methods or function but > in that > of the module = file. It is very likely that several methods/ > function or > related to the same paper will appear. It is as well likely that > they appear > in the same class/file. Also, it's coherent to put them close to the > AUTHOR: > part since both are some kinds of acknowledgment (one for the > mathematical > idea, one for the implantation).
I'm not sure this will be a good thing--it might make a cleaner reference manual but I think docstrings are most used via the powerful introspection that's available in Sage, and we want to put as much as possible (e.g. references) right at the user's fingertips. - Robert --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
