Johan S. H. Rosenkilde 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
Well, first of all it is stupid to use such a short abbreviation, even without a year. Presumably it was introduced when references were local, so we may create a (meta-)ticket to change all of such occurrences. > 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... Well, not that long ago, docbuilding in parallel wasn't even possible (h/t mostly John Palmieri IIRC, with a few others); before, the whole reference manual had been one monolithic block. Of course the documentation keeps growing (and hence also Sphinx' memory footprint and runtime), but it was IMHO always double dog-slow. But especially building plot* gets slower and slower because people keep adding more and more "nice" things I guess. To me the most annoying thing is that "make doc" (which ptestlong for example for no reason depends on) meanwhile even takes ages when Sphinx does nothing, or almost nothing, because nothing changed. (My recent impression is though that some files accidentally get touched somehow, such that they to Sphinx look modified. I can't give any concrete example, just noticed.) -leif -- 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.
