I just ran into a doc issue that has been bothering me for years: global uniqueness of reference labels in Sphinx. For instance, in sage.coding.code_construction, we have:
.. [HP] W. C. Huffman, V. Pless, Fundamentals of Error-Correcting Codes, Cambridge Univ. Press, 2003. This means I cannot use [HP] as a reference label in another file, say sage.coding.hamming_code. Writing "[HP]_" in doc-string globally in Sage *should* generate a link to sage.coding.code_construction. It does in fact give me a compilation error :-S This seems to be the recommended way of doing it in Sphinx. Am I the only one who thinks this is crazy? Can/should we do something about this? On a related note, the Developer's manual doesn't mention this problem, or the fact that people should use ReST references (i.e. remember the underscore), and that REFERENCES blocks should be at the top of the module (and not in individual methods/functions). A quick grep showed lots of recent code violating this convention. Is this sort of mess the reason Sphinx is so terribly slow, I wonder... Best, Johan -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at https://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
