On Monday, September 5, 2016 at 5:56:48 PM UTC-7, Andrew wrote: > > In any large document, such as the sage manuals, there are bound to be > uniqueness issues with the choice of labels for references. The best way to > resolve this is for us to start using a specified format for the > references. Currently we do not even have guidelines for this so it is not > surprising that different people do different things. > > It would also help to have the references appearing in one file, as > William suggests, so that people can find them easily and check that the > label does not already exist. A reference file would also help ensure that > people use whatever format is agreed upon for the references. >
See https://trac.sagemath.org/ticket/21454. John > > Andrew > > On Tuesday, 6 September 2016 07:49:42 UTC+10, John H Palmieri wrote: >> >> >> >> On Monday, September 5, 2016 at 11:20:15 AM UTC-7, Johan S. R. Nielsen >> wrote: >>> >>> leif writes: >>> >> ... [HP] W. C. Huffman, V. Pless, Fundamentals of Error-Correcting >>> >> Codes, Cambridge Univ. Press, 2003. >>> > >>> > 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. >>> >>> Agreed. The inspiration for new developers in the Sage Development >>> manual uses the citation label "[SC]": >>> >>> >>> http://doc.sagemath.org/html/en/developer/coding_basics.html#documentation-strings >>> >>> >>> >>> >> 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.) >>> >>> Yes, doing `make doc` goes through every chapter of the manual, very >>> carefully determining that nothing changed. I often use "./sage >>> -docbuild reference/<chapter> html" instead, but that seems even more >>> fragile than regular doc-building. >>> >>> Jeroen Demeyer writes: >>> > General comment to all people complaining about Sphinx: reviewing >>> > existing Sphinx-related tickets such as #20577 will show that you >>> > actually care and will encourage other Sage developers to continue >>> > working on Sphinx. >>> >>> Thanks for your work! Are there tickets (or upstream-not-merged-changes) >>> which would make Sphinx faster or have better, less fragile incremental >>> building? >>> >>> Best, >>> Johan >>> >> >> Regarding speed, there are two issues: >> >> 1. Building the documentation from scratch. I don't know if we can >> expect this to go any faster. The PDF version of the documentation is 3,474 >> pages long. No, wait, that's just the contribution from >> references/combinat: the whole reference manual is 18,442 pages long. I can >> build this on my machine in about 8 minutes, and this does not seem >> unreasonable. Am I wrong about this? (It could be sped up a bit for >> parallel builds if the largest pieces, e.g., reference/combinat, were >> broken into smaller pieces, but I don't know how much speed increase we can >> hope for.) >> >> 2. Incremental builds. I agree that this is not very fast, and it doesn't >> play well when switching between git branches: too much of the >> documentation is rebuilt, and the docbuild often fails (e.g., if Python >> source files have been removed from one branch to another). I don't know >> how to fix these issues. >> >> By the way, the main work for allowing parallel docbuilding was done by >> Mitesh Patel, not me (although I helped a little). >> >> -- >> John >> >> -- 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.