diff --git a/src/doc/en/developer/portability_testing.rst b/src/doc/en/developer/portability_testing.rst index 1312adc9555..9df5331c8ab 100644 --- a/src/doc/en/developer/portability_testing.rst +++ b/src/doc/en/developer/portability_testing.rst @@ -60,13 +60,33 @@ Make sure that your Docker client is configured to provide enough RAM to the containers (8 GB are a good choice). In Docker Desktop this setting is in Preferences -> Resources -> Advanced. +As an alternative, you can also run Docker in GitHub Codespaces +(or another cloud service) using a container with the Docker-in-Docker +feature. Sage provides a suitable dev container configuration +`.devcontainer/tox-docker-in-docker +`_. + +.. only:: html + + .. |codespace-tox-docker-in-docker| image:: https://github.com/codespaces/badge.svg + :target: https://codespaces.new/sagemath/sage?devcontainer_path=.devcontainer%2Ftox-docker-in-docker%2Fdevcontainer.json + + .. list-table:: + :widths: 25 60 + :header-rows: 0 + + * - `tox-docker-in-docker + `_ + - |codespace-tox-docker-in-docker| + All examples in this section were obtained using Docker Desktop for Mac; but the `command-line user interface `_ for the other platforms is identical. All major Linux distributions provide ready-to-use Docker images, -which are published via `Docker Hub `_. For +which are published via `Docker Hub `_ +or other container registries. For example, to run the current stable (LTS) version of Ubuntu interactively, you can use the shell command:: @@ -573,14 +593,22 @@ Automatic Docker-based build testing using tox `tox `_ is a Python package that is widely used for automating tests of Python projects. -Install ``tox`` for use with your system Python, for example using:: +If you are using Docker locally, install ``tox`` for use with your system Python, +for example using:: [mkoeppe@sage sage]$ pip install --user tox +If you run Docker-in-Docker on GitHub Codespaces using our dev container +configuration `.devcontainer/tox-docker-in-docker +`_, +``tox`` is already installed. + +Sage provides a sophisticated tox configuration in the file +``$SAGE_ROOT/tox.ini`` for the purpose of portability testing. + A tox "environment" is identified by a symbolic name composed of several `Tox "factors" -`_, -which are defined in the file ``$SAGE_ROOT/tox.ini``. +`_. The **technology** factor describes how the environment is run: