tox.ini [local]: Pass MAKE environment variable, do not default to 'm…

…ake -j12', change default target to 'build', add doc

tox.ini

@@ -35,8 +35,34 @@ envlist =
     ### However, "local" targets install in a separate prefix (SAGE_LOCAL=.tox/TOXENV/local)
     ### rather than "local/" and also place log files into .tox/TOXENV/log, where TOXENV
     ### is the name of the environment.
+    #
     # The "local-homebrew" toxenvs create an "isolated" homebrew installation (not in /usr/local).
     # (However, many configure scripts still look for stuff in /usr/local.)
+    #
+    # By default, it runs "make build" (after bootstrapping and configuring)
+    # with SAGE_CHECK=yes and SAGE_CHECK_PACKAGES set to a good default,
+    # and V=0 so that screen output is limited.
+    #
+    #   $ tox -e local-homebrew-macos-standard
+    #
+    # The value of MAKE is picked up from the environment, so you can do:
+    #
+    #   $ MAKE="make -j8" tox -e local-homebrew-macos-standard
+    #
+    # Build targets can be passed as positional arguments (separated from tox options by "--"):
+    #
+    #   $ tox -e local-homebrew-macos-standard -- ppl
+    #   $ tox -e local-homebrew-macos-standard -- build ptest
+    #
+    # Also make variables can be passed as positional arguments; for example, to run the
+    # test suite:
+    #
+    #   $ tox -e local-homebrew-macos-standard -- SAGE_CHECK=no build ptest SAGE_NUM_THREADS=4
+    #
+    # Or to rebuild a package with verbose output:
+    #
+    #   $ tox -e local-homebrew-macos-standard -- ppl-clean ppl V=1
+    #
     local-homebrew-macos
    }-{minimal,standard,maximal},
    ### The "local-direct" toxenv passes the whole environment on to the sage build.
@@ -47,7 +73,8 @@ skipsdist = true
 
 [testenv]
 passenv =
-    EXTRA_DOCKER_BUILD_ARGS
+    docker:       EXTRA_DOCKER_BUILD_ARGS
+    local:        MAKE
     local-direct: *
 setenv =
     # Set this to 'force' instead of 'yes' to make it an error if an spkg with spkg-configure and system package
@@ -215,7 +242,7 @@ commands =
     docker:        {env:EXTRA_DOCKER_BUILD_ARGS:}
     # pathpy checksuite needs tox. #28728: gap fails its test suite.
     # linbox/cysignals testsuites fail.
-    local:         bash -c 'export PATH={env:PATH} MAKE="make -j12" && {env:SETENV} && ./bootstrap && ./configure --prefix={envdir}/local && make -k V=0 base-toolchain && SAGE_CHECK=yes SAGE_CHECK_PACKAGES="!cython,!r,!python3,!python2,!nose,!pathpy,!gap,!cysignals,!linbox" make -k V=0 {posargs:numpy build}'
+    local:         bash -c 'export PATH={env:PATH} && {env:SETENV} && ./bootstrap && ./configure --prefix={envdir}/local && make -k V=0 base-toolchain && SAGE_CHECK=yes SAGE_CHECK_PACKAGES="!cython,!r,!python3,!python2,!nose,!pathpy,!gap,!cysignals,!linbox" make -k V=0 {posargs:build}'
 
 [testenv:check_configure]
 ## Test that configure behaves properly