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.

Reply via email to