On Mon, Sep 5, 2016 at 11:46 AM, Johan S. H. Rosenkilde <santaph...@gmail.com> wrote: > 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...
This might be a bug in Sphinx but I'm not 100% certain the bug I have in mind affects reuse of reference labels as well. If it is the bug I have in mind the patch in this ticket, which needs review, would fix it: https://trac.sagemath.org/ticket/21044 -- 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.
