Update documentation

Author: Matthias Koeppe

src/bin/sage-runtests

@@ -26,7 +26,8 @@ if __name__ == "__main__":
                                                  ".py, .pyx, .pxd, .pxi, .sage, .spyx, .tex, .rst.")
     parser.add_argument("-p", "--nthreads", dest="nthreads",
                         type=int, nargs='?', const=0, default=1, metavar="N",
-                        help="tests in parallel using N threads with 0 interpreted as max(2, min(8, cpu_count()))")
+                        help="test in parallel using N threads, with 0 interpreted as max(2, min(8, cpu_count())); "
+                        "when run under the control of the GNU make jobserver (make -j), request as most N job slots")
     parser.add_argument("-T", "--timeout", type=int, default=-1, help="timeout (in seconds) for doctesting one file, 0 for no timeout")
     what = parser.add_mutually_exclusive_group()
     what.add_argument("-a", "--all", action="store_true", default=False, help="test all files in the Sage library")

src/doc/en/developer/doctesting.rst

@@ -512,7 +512,10 @@ doctests.  This determines the number of threads by reading the
 environment variable :envvar:`MAKE`: if it is set to ``make -j12``, then
 use 12 threads.  If :envvar:`MAKE` is not set, then by default it uses
 the number of CPU cores (as determined by the Python function
-``multiprocessing.cpu_count()``) with a minimum of 2 and a maximum of 8.
+:func:`multiprocessing.cpu_count`) with a minimum of 2 and a maximum of 8.
+(When this runs under the control of the `GNU make jobserver
+<https://www.gnu.org/software/make/manual/make.html#Parallel>`_, then Sage
+will request as most this number of job slots.)
 
 In any case, this will test the Sage library with multiple threads::
 

src/doc/en/installation/source.rst

@@ -782,14 +782,19 @@ Here are some of the more commonly used variables affecting the build process:
       Some users on single-core macOS machines have reported problems when
       building Sage with ``MAKE='make -jNUM'`` with ``NUM`` greater than one.
 
-- :envvar:`SAGE_NUM_THREADS` - if set to a number, then when building the
-  documentation, parallel doctesting, or running ``sage -b``, use this many
-  threads.
+- :envvar:`SAGE_NUM_THREADS` - if set to a number, then when rebuilding with
+  ``sage -b`` or parallel doctesting with ``sage -t -p 0``, use at most this
+  many threads.
+
   If this is not set, then determine the number of threads using the value of
   the :envvar:`MAKE` (see above) or :envvar:`MAKEFLAGS` environment variables.
-  If none of these specifies a number of jobs, use one thread (except for
-  parallel testing: there we use a default of the number of CPU cores, with a
-  maximum of 8 and a minimum of 2).
+  If none of these specifies a number of jobs,
+  - ``sage -b`` only uses one thread
+  - ``sage -t -p 0`` uses a default of the number of CPU cores, with a
+    maximum of 8 and a minimum of 2.
+
+  When ``sage -t -p`` runs under the control of the GNU ``make``
+  jobserver, then Sage will request as most this number of job slots.
 
 - :envvar:`V` - if set to ``0``, silence the build.  Instead of
   showing a detailed compilation log, only one line of output is shown