ReST References in Sphinx and uniqueness

[Johan S. H. Rosenkilde]

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

[Dima Pasechnik]

On Monday, September 5, 2016 at 9:46:22 AM UTC, Johan S. R. Nielsen 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

hmm, I think it should work. E.g. [BH12]_, defined in combinat/matrices/hadamard_matrix.py, does work:

$ grep -R BH12 .

./coding/linear_code.py:        [BH12]).

./graphs/generators/families.py:    Seidel switching class of the latter graph (see [BH12]_) coincides with the set

./graphs/generators/classical_geometries.py:    For more information, see Sect. 9.9 of [BH12]_ and [BvL84]_. Note that the `page of

./graphs/generators/classical_geometries.py:    For more information, see Sect. 9.9 of [BH12]_ and series C14 in [Hu75]_.

./graphs/strongly_regular_db.pyx:    strongly regular graph. See [BH12]_ and [BI84]_ for details.

./graphs/strongly_regular_db.pyx:    Return g and n, if they exist. See Sect. 9.1 of [BH12]_ for details.

./graphs/strongly_regular_db.pyx:    Sect.9.8.3 of [BH12]_.

./combinat/matrices/hadamard_matrix.py:    [BH12]_. For the case `n=324`, see :func:`RSHCD_324` and [CP16]_.

./combinat/matrices/hadamard_matrix.py:    .. [BH12] \A. Brouwer and W. Haemers,

./combinat/matrices/hadamard_matrix.py:    `(n-1,(n-2)/2,(n-6)/4,(n-2)/4)`, see Sec.10.4 of [BH12]_. Thus we build `C`

./combinat/designs/twographs.py:things such as constructing the complement two-graph, cf. [BH12]_.

./combinat/designs/incidence_structures.py:        An incidence structure is a generalized quadrangle iff (see [BH12]_,

(besides the missing _ in linear_code, there are more _ missing there :-))

Dima

[Erik Bray]

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

[Dima Pasechnik]

I've opened #21418 to deal with refs mess in coding/

Should be ready for review soon (there are duplicate references, missed _ in []_, wrong tabulation in docstrings, etc

[Johan S. H. Rosenkilde]

I should perhaps clarify my main question:

Isn't the unique citation as used in Sphinx a Bad Idea for Sage?

Most source files in Sage are not ordered, and if we refer to document
[X] in two different source files, we currently have three options:

1) Arbitrarily define [X] in one file and refer to it in the other.
2) Define [X1] in one file and [X2] in the other.
3) Use non-ReST syntax for references (i.e. no underscore in links and
" - " instead of ".. " in definitions) and define [X] in both files.

All three are bad solutions in my opinion, and all three are in active
use in Sage (perhaps 2. inadvertently rather than intentionally).

Note that with 1., in the HTML-documentation of the second file, a user
will be taken to the doc of the first file when clicking the link. In
the Sage terminal, users will not see the def of [X] (and can't find it
since it's in a completely different file).

Personally, I'd rather go with 3. than 1. even though it means giving
the same bibliographic information in every source file it is used.

My unclear post had two other, vaguely related points:

A) I'm currently fighting with Sphinx over a bug/userbug in citations in
sage.coding. Thanks for #21418, Dima.

B) A general rant that Sphinx compilation is much, much slower than what
it accomplishes gives it any right to be. It also horribly breaks
much more often than any other part of the compilation chain (for me,
at least), forcing me to do `make doc-clean && make` basically every
time I want to inspect HTML documentation. Apparently the project's
name comes from the riddle of its ineptitude...

Best,
Johan

--

[Dima Pasechnik]

On Monday, September 5, 2016 at 11:56:35 AM UTC, Johan S. R. Nielsen wrote:

I should perhaps clarify my main question:

Isn't the unique citation as used in Sphinx a Bad Idea for Sage?

Most source files in Sage are not ordered, and if we refer to document
[X] in two different source files, we currently have three options:

1) Arbitrarily define [X] in one file and refer to it in the other.
2) Define [X1] in one file and [X2] in the other.
3) Use non-ReST syntax for references (i.e. no underscore in links and
   " - " instead of ".. " in definitions) and define [X] in both files.

All three are bad solutions in my opinion, and all three are in active
use in Sage (perhaps 2. inadvertently rather than intentionally).

Note that with 1., in the HTML-documentation of the second file, a user
will be taken to the doc of the first file when clicking the link. In
the Sage terminal, users will not see the def of [X] (and can't find it
since it's in a completely different file).

only a small minority of Sage users actually use terminal.

And in any event, demanding a bibliography reference in terminal is

a bit over the top (even people who live in terminal, like me, would use a web browser to

look at references, and thus use HTML documentation).

I also totally don't see a value of having a reference to the same thing in every file. You can use grep if you must not leave the terminal.

Also, in Sage, you can use search_src("\[HP\]\ " to find a place [HP] is defined:

sage: search_src("\[HP\]\ ")

coding/linear_code.py:111:.. [HP] \W. C. Huffman and V. Pless, Fundamentals of error-correcting codes,

Perhaps it might make more sense to concentrate most of the references to a topic in one file.

 

Personally, I'd rather go with 3. than 1. even though it means giving
the same bibliographic information in every source file it is used.

please don't... this breaks HTML docs badly.

 

My unclear post had two other, vaguely related points:

A) I'm currently fighting with Sphinx over a bug/userbug in citations in
   sage.coding. Thanks for #21418, Dima.

you are welcome - it's indeed sometimes not easy to find these errors.

But do feel free to ask pointed questions if you get stuck.

 

B) A general rant that Sphinx compilation is much, much slower than what
   it accomplishes gives it any right to be. It also horribly breaks
   much more often than any other part of the compilation chain (for me,
   at least), forcing me to do `make doc-clean && make` basically every
   time I want to inspect HTML documentation. Apparently the project's
   name comes from the riddle of its ineptitude...

I agree that speeding up this is very important for smoother development.

Only it seems that our options are not very broad here, unless we get involved in

speeding it up ourselves....

Dima

[Travis Scrimshaw]

I should perhaps clarify my main question:

Isn't the unique citation as used in Sphinx a Bad Idea for Sage?

I don't think so. How else could you resolve a reference in a separate file? It would likely lead to a lot of duplication of reference information because of this.

Most source files in Sage are not ordered, and if we refer to document
[X] in two different source files, we currently have three options:

1) Arbitrarily define [X] in one file and refer to it in the other.
2) Define [X1] in one file and [X2] in the other.
3) Use non-ReST syntax for references (i.e. no underscore in links and
   " - " instead of ".. " in definitions) and define [X] in both files.

All three are bad solutions in my opinion, and all three are in active
use in Sage (perhaps 2. inadvertently rather than intentionally).

Note that with 1., in the HTML-documentation of the second file, a user
will be taken to the doc of the first file when clicking the link. In
the Sage terminal, users will not see the def of [X] (and can't find it
since it's in a completely different file).

Personally, I'd rather go with 3. than 1. even though it means giving
the same bibliographic information in every source file it is used.

It depends on what you want to achieve. We currently do all 3 in Sage and none of them doesn't cause any problems.

B) A general rant that Sphinx compilation is much, much slower than what
   it accomplishes gives it any right to be. It also horribly breaks
   much more often than any other part of the compilation chain (for me,
   at least), forcing me to do `make doc-clean && make` basically every
   time I want to inspect HTML documentation. Apparently the project's
   name comes from the riddle of its ineptitude...

Just FYI, you can just do `make build` to skip dealing with the documentation. However, I agree, the docbuilding is fairly fragile (especially when files have been deleted due to, e.g., changing branches).

Best,
Travis
 

[Johan S. H. Rosenkilde]

Dima Pasechnik writes:
> only a small minority of Sage users actually use terminal.

How do you know that? Seriously, I'd like to know how our users
distributed across interfaces. It's my impression that quite a lot of
casual users of Sage begin with terminal use and never leave it.

> And in any event, demanding a bibliography reference in terminal is
> a bit over the top (even people who live in terminal, like me, would use a
> web browser to
> look at references, and thus use HTML documentation).

Why? The documentation could automatically create a REFERENCE block at
the end of any method/function/etc. with the bibliographic information
of works cited in that doc string.

> I also totally don't see a value of having a reference to the same thing in
> every file. You can use grep if you must not leave the terminal.
> Also, in Sage, you can use search_src("\[HP\]\ " to find a place [HP] is
> defined:

The value is that, as a user, when I press "myfunc?<tab>" I can *see*
what the reference means without having to spend time and mental effort
grep'ing or search_src'ing. Ask a user what he prefers.

> please don't... this breaks HTML docs badly.

How? I might be wrong (I clearly don't understand Sphinx well), but it
seems that all it breaks is that no hyperlink appears -- but I don't
need that since the bib-information is *right there*.

What worries me most is that it leads to possibly mutually
inconsistent versions of the same bib-information spread all over the
place.

> you are welcome - it's indeed sometimes not easy to find these errors.
> But do feel free to ask pointed questions if you get stuck.

Thanks. I've been working on #20908 and it seems that modifying
an index.rst file leads more often to corruption (and hence `make
doc-build && make`) than most other modifications. That or I am just
unlucky...

> I agree that speeding up this is very important for smoother development.
> Only it seems that our options are not very broad here, unless we get
> involved in speeding it up ourselves....

My conclusion too, after browsing the competition. What I don't
understand is that "Sphinx bad performance" reveals almost no useful
discussions on Google. I would think Sphinx was used on all large Python
projects. Could it be that the way we are calling Sphinx leads to bad
performance?

Travis Scrimshaw writes:
> I don't think so. How else could you resolve a reference in a separate
> file? It would likely lead to a lot of duplication of reference information
> because of this.

> ...

> It depends on what you want to achieve. We currently do all 3 in Sage and
> none of them doesn't cause any problems.

Agreed, unique bib-information is Good(tm); that's why many of us use
BibTeX and possibly Zotero or similar tools. It's just that Sphinx's
incarnation of this is not very smart: the bibliographic information
ends up in a random source file. As a user, I would be confused by
clicking in the doc of module A on some citation, and ending up in the
doc of mostly unrelated module B.

> It depends on what you want to achieve. We currently do all 3 in Sage and
> none of them doesn't cause any problems.

Is the extra negation intentional? What we currently do in Sage is
inconsistent, has lots of duplication of reference information, is not
user-friendly in the way I just described *and* is badly documented. Is
this not a problem?

Best,
Johan

[leif]

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

[David Joyner]

On Mon, Sep 5, 2016 at 11:01 AM, Johan S. H. Rosenkilde
<santa...@gmail.com> wrote:
> Dima Pasechnik writes:
>> only a small minority of Sage users actually use terminal.
>
> How do you know that? Seriously, I'd like to know how our users
> distributed across interfaces. It's my impression that quite a lot of
> casual users of Sage begin with terminal use and never leave it.
>

There was a survey done some years ago. Relatively few people (like
me) almost exclusively used the terminal. If memory serves, the number
of terminal users was under 5%.

>> And in any event, demanding a bibliography reference in terminal is
>> a bit over the top (even people who live in terminal, like me, would use a
>> web browser to
>> look at references, and thus use HTML documentation).
>
>

> --
> 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+...@googlegroups.com.
> To post to this group, send email to sage-...@googlegroups.com.
> Visit this group at https://groups.google.com/group/sage-devel.
> For more options, visit https://groups.google.com/d/optout.

[Daniel Krenn]

On 2016-09-05 16:40, Travis Scrimshaw wrote:
> [...] However, I agree, the docbuilding is fairly fragile

> (especially when files have been deleted due to, e.g., changing branches).

This annoys me as well.
Can we do something against these troubles coming from deleted files?

Best,

Daniel

[Jeroen Demeyer]

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.

[William Stein]

On Mon, Sep 5, 2016 at 4:56 AM, Johan S. H. Rosenkilde
<santa...@gmail.com> wrote:
> I should perhaps clarify my main question:
>
> Isn't the unique citation as used in Sphinx a Bad Idea for Sage?
>
> Most source files in Sage are not ordered, and if we refer to document
> [X] in two different source files, we currently have three options:
>
> 1) Arbitrarily define [X] in one file and refer to it in the other.

An extreme version of 1 would be to create one new file called "ref.py"
(at the very top level), and move all references there.

When I use bibtex I put all my bibliographic references in a single
file, biblio.bib, and then reference that file from various .tex
files.

-- William

[Johan S. H. Rosenkilde]

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.

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

[John H Palmieri]

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

[Andrew]

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.

Andrew

[Johan S. H. Rosenkilde]

> 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.

Agreed. The Developer's Manual could be improved in this respect.

> 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.

+1

Best,
Johan

[Johan S. H. Rosenkilde]

> 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.)

OK, this is good to know. It takes considerably longer on my machine, so
there is something I'm really not doing right (possibly not having
parallel build enabled). I'll experiment with this.

8 minutes from a clean build is not impressive IMHO, but perhaps it's
then not the most important piece of the compilation process to improve.

Best,
Johan

[Dima Pasechnik]

On Tuesday, September 6, 2016 at 5:59:19 AM UTC, Johan S. R. Nielsen wrote:

> 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.)

OK, this is good to know. It takes considerably longer on my machine, so
there is something I'm really not doing right (possibly not having
parallel build enabled). I'll experiment with this.

do you mean you don't do 

export MAKE="make -j4"

$MAKE

 

(here 4 is the number of cores; replace with the correct value for your setup; most modern desktops now have 8, I think)

8 minutes from a clean build is not impressive IMHO, but perhaps it's
then not the most important piece of the compilation process to improve.

for 20,000 pages? Circa 40 pages per second  isn't too bad (for TeX, say).

 

Best,
Johan

[Johan S. H. Rosenkilde]

Dima Pasechnik writes:
>
> do you mean you don't do
>
> export MAKE="make -j4"
> $MAKE
>
> (here 4 is the number of cores; replace with the correct value for your
> setup; most modern desktops now have 8, I think)

I'm probably in the stone age, and possibly suffer from a catastrophe
bias, but a few years ago, my Sage builds would often fail when I added
"-j4". I don't remember whether doc-building was often the culprit or
not. Anyway, I never consistently started to use it. I take it that
everyone else does, so I should as well.

>> 8 minutes from a clean build is not impressive IMHO, but perhaps it's
>> then not the most important piece of the compilation process to improve.
>
> for 20,000 pages? Circa 40 pages per second isn't too bad (for TeX, say).

Is the pdf compilation very important? Isn't everyone using the HTML one
anyway? 40 HTML pages/second is not impressive. But as I said, probably
it would help a lot if just the incremental building was more robust.

Best,
Johan

[Samuel Lelievre]

2016-09-06 17:39:38 UTC+2, Jeroen Demeyer:

For instance

https://trac.sagemath.org/query?order=status&desc=1&summary=~sphinx&or&keywords=~sphinx

or for a more exhaustive list

https://trac.sagemath.org/query?order=status&desc=1&summary=~sphinx&or&keywords=~sphinx&or&description=~sphinx

[Sébastien Labbé]

On Monday, September 5, 2016 at 11:46:22 AM UTC+2, Johan S. R. Nielsen wrote:

I just ran into a doc issue that has been bothering me for years: global
uniqueness of reference labels in Sphinx.

Use two underscore instead of just one.

...at least, it works for links, I don't know for ref and citations. For example__ example__

__ http://firsturl.com
__ http://secondurl.com

should not give a warning because "example" is used twice.

[Nicolas M. Thiery]

See also the notes about the work that was done at Sage Days 77 with a
Sphinx dev, in particular about analyzing performance issues, and how
to tackle them, in particular using Sphinx's native parallel build
features:

https://www.lri.fr/etherpad/p/sage-days77-documentation

Well, right now the above link is down, but I assume it will be back
soon). We really need to move this material back to the wiki!

Cheers,
Nicolas
--
Nicolas M. Thiéry "Isil" <nth...@users.sf.net>
http://Nicolas.Thiery.name/

[John H Palmieri]

It also takes less time if you don't include plots: maybe 5 minutes for me instead of 8.

[John H Palmieri]

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

 

[leif]

John H Palmieri wrote:
> It also takes less time if you don't include plots: maybe 5 minutes for
> me instead of 8.

But sooner or later we'll have to split combinat I think, as you
mentioned, since with N threads you're just waiting faster (or rather
"in parallel") for the last part to finish, similar to building Sage
from scratch, where I meanwhile always have to wait for just SciPy
(although during the build, the number of threads actually used a couple
of times already drops down to just one or two).


Interestingly, AFAICT in (HTML) docbuilding I/O isn't an issue (perhaps
unless your disk is very very slow, or the box is in addition swapping).


-leif

> improve..
>
> Best,
> Johan