Manual edits for using :sage_root:

Author: Matthias Koeppe

src/doc/en/developer/coding_basics.rst

@@ -432,7 +432,7 @@ information. You can use the existing functions of Sage as templates.
 
    The bibliographical reference should go in Sage's master
    bibliography file,
-   :file:`SAGE_ROOT/src/doc/en/reference/references/index.rst`:
+   :sage_root:`src/doc/en/reference/references/index.rst`:
 
    .. CODE-BLOCK:: rest
 
@@ -605,7 +605,7 @@ Sage's master **BIBLIOGRAPHY** file
 
 All bibliographical references should be stored in the master
 bibliography file,
-:file:`SAGE_ROOT/src/doc/en/reference/references/index.rst`, in the
+:sage_root:`src/doc/en/reference/references/index.rst`, in the
 format
 
 .. CODE-BLOCK:: rest

src/doc/en/developer/coding_in_other.rst

@@ -43,7 +43,7 @@ polynomial or matrix, will have our new method. So you can do
 ``PariError`` in this case.
 
 The ``gen`` class is defined in
-:file:`SAGE_ROOT/src/sage/libs/cypari2/gen.pyx`, and this is where we
+:sage_root:`src/sage/libs/cypari2/gen.pyx`, and this is where we
 add the method ``matfrobenius``:
 
 .. CODE-BLOCK:: cython
@@ -194,7 +194,7 @@ Note the ``'"G"'`` which is evaluated in GAP as the string ``"G"``.
 The purpose of this section is to use this example to show how one
 might write a Python/Sage program whose input is, say, ``('G',2)`` and
 whose output is the matrix above (but as a Sage Matrix---see the code
-in the directory :file:`SAGE_ROOT/src/sage/matrix/` and the
+in the directory :sage_root:`src/sage/matrix/` and the
 corresponding parts of the Sage reference manual).
 
 First, the input must be converted into strings consisting of legal

src/doc/en/developer/packaging.rst

@@ -168,16 +168,16 @@ Third-party packages in Sage consist of two parts:
    instead.
 
 #. The build scripts and associated files are in a subdirectory
-   :sage_root:`build/pkgs/<package>`, where you replace ``<package>``
-   with a lower-case version of the upstream project name. If the
+   of :sage_root:`build/pkgs/` whose name is the lower-case version of
+   the upstream project name. If the
    project name contains characters which are not alphanumeric
    and are not an underscore, those characters should be removed
    or replaced by an underscore. For example, the project
    ``FFLAS-FFPACK`` is called ``fflas_ffpack`` in Sage.
 
 As an example, let us consider a hypothetical FoO project. They
 (upstream) distribute a tarball ``FoO-1.3.tar.gz`` (that will be
-automatically placed in :sage_root:`upstream` during the installation
+automatically placed in :file:`SAGE_ROOT/upstream` during the installation
 process). To package it in Sage, we create a subdirectory containing as
 a minimum the following files:
 
@@ -394,7 +394,7 @@ Helper functions
 
 In the ``spkg-build``, ``spkg-install``, and ``spkg-check`` scripts,
 the following functions are available. They are defined in the file
-``$SAGE_ROOT/build/bin/sage-dist-helpers``, if you want to look at the
+:sage_root:`build/bin/sage-dist-helpers`, if you want to look at the
 source code.  They should be used to make sure that appropriate
 variables are set and to avoid code duplication. These function names
 begin with ``sdh_``, which stands for "Sage-distribution helper".

src/doc/en/developer/portability_testing.rst

@@ -619,7 +619,7 @@ 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.
+:sage_root:`tox.ini` for the purpose of portability testing.
 
 A tox "environment" is identified by a symbolic name composed of
 several `Tox "factors"
@@ -639,7 +639,7 @@ The next two factors determine the host system configuration: The
   ``archlinux-latest``, ``fedora-30``, ``slackware-14.2``,
   ``centos-7-i386``, and ``ubuntu-bionic-arm64``.
 
-- See ``$SAGE_ROOT/tox.ini`` for a complete list, and to which images
+- See :sage_root:`tox.ini` for a complete list, and to which images
   on Docker hub they correspond.
 
 The **packages factor** describes a list of system packages to be
@@ -919,7 +919,7 @@ a Homebrew installation in ``/usr/local`` that you may have.
 
 The test script sets the ``PATH`` to the ``bin`` directory of the
 Homebrew prefix, followed by ``/usr/bin:/bin:/usr/sbin:/sbin``.  It
-then uses the script ``$SAGE_ROOT/.homebrew-build-env`` to set
+then uses the script :sage_root:`.homebrew-build-env` to set
 environment variables so that Sage's build scripts will find
 "keg-only" packages such as ``gettext``.
 
@@ -1002,13 +1002,11 @@ on every release tag.
 
 This is defined in the files
 
-- `$SAGE_ROOT/.github/workflows/ci-linux.yml
-  <https://github.com/sagemath/sage/tree/develop/.github/workflows/ci-linux.yml>`_
-  (which calls `$SAGE_ROOT/.github/workflows/docker.yml
-  <https://github.com/sagemath/sage/tree/develop/.github/workflows/docker.yml>`_) and
+- :sage_root:`.github/workflows/ci-linux.yml`
+  (which calls :sage_root:`.github/workflows/docker.yml`) and
 
-- `$SAGE_ROOT/.github/workflows/ci-macos.yml
-  <https://github.com/sagemath/sage/tree/develop/.github/workflows/ci-macos.yml>`_.
+- :sage_root:`.github/workflows/ci-macos.yml`
+  (which calls :sage_root:`.github/workflows/macos.yml`).
 
 GitHub Actions runs these build jobs on 2-core machines with 7 GB of
 RAM memory and 14 GB of SSD disk space, cf.
@@ -1236,8 +1234,7 @@ Once VS Code starts configuring the dev container, by clicking on "show log",
 you can see what it does:
 
 - It pulls the prebuilt image from ghcr.io (via
-  `$SAGE_ROOT/.devcontainer/portability-Dockerfile
-  <https://github.com/sagemath/sage/tree/develop/.devcontainer/portability-Dockerfile>`_);
+  :sage_root:`.devcontainer/portability-Dockerfile`);
   note that these are multi-gigabyte images, so it may take a while.
 
 - As part of the "onCreateCommand", it installs additional system packages to
@@ -1270,8 +1267,7 @@ The Sage source tree contains premade configuration files for all platforms
 for which our portability CI builds Docker images, both in the ``minimal`` and
 ``standard`` system package configurations. The configuration files can be
 generated using the command ``tox -e update_docker_platforms`` (see
-`$SAGE_ROOT/tox.ini <https://github.com/sagemath/sage/tree/develop/tox.ini>`_
-for environment variables that take effect).
+:sage_root:`tox.ini` for environment variables that take effect).
 
 You can edit a copy of the configuration file to change to a different platform, another
 version, or build stage.  After editing the configuration file, run "Dev Containers: Rebuild Container" from the command
@@ -1284,7 +1280,7 @@ for more information.
 In addition to the
 ``$SAGE_ROOT/.devcontainer/portability-.../devcontainer.json`` files, Sage also
 provides several other sample ``devcontainer.json`` configuration files in the
-directory ``$SAGE_ROOT/.devcontainer``.
+directory :sage_root:`.devcontainer`.
 
 Files named ``$SAGE_ROOT/.devcontainer/develop-.../devcontainer.json`` configure
 containers from a public Docker image that provides SageMath and then updates the

src/doc/en/installation/source.rst

@@ -528,14 +528,14 @@ Installation steps
    There are different possibilities to make using Sage a little easier:
 
    - Make a symbolic link from :file:`/usr/local/bin/sage` (or another
-     directory in your :envvar:`PATH`) to :file:`$SAGE_ROOT/sage`::
+     directory in your :envvar:`PATH`) to :sage_root:`sage`::
 
          $ ln -s /path/to/sage_root/sage /usr/local/bin/sage
 
      Now simply typing ``sage`` from any directory should be sufficient to run
      Sage.
 
-   - Copy :file:`$SAGE_ROOT/sage` to a location in your :envvar:`PATH`.
+   - Copy :sage_root:`sage` to a location in your :envvar:`PATH`.
      If you do this, make sure you edit the line:
 
      .. CODE-BLOCK:: bash
@@ -573,7 +573,7 @@ Installation steps
      right clicking the mouse on the icon).
 
    - On Linux and macOS systems, you can make an alias to
-     :file:`$SAGE_ROOT/sage`.
+     :sage_root:`sage`.
      For example, put something similar to the following line in your
      :file:`.bashrc` file:
 
@@ -777,7 +777,7 @@ Sage-specific environment variables controlling the build process
   the nearest mirrors.
 
   This sequence of operations is defined by the files in the directory
-  :file:`$SAGE_ROOT/.upstream.d`.
+  :sage_root:`.upstream.d`.
 
 .. envvar:: SAGE_NUM_THREADS
 

src/doc/en/reference/repl/startup.rst

@@ -8,7 +8,7 @@ The sagerc shell script
 
 The *bash shell script* :file:`$DOT_SAGE/sagerc` (with the default
 value of :envvar:`DOT_SAGE`, this is :file:`~/.sage/sagerc`) is read
-by :file:`$SAGE_ROOT/spkg/bin/sage-env` after Sage has set its
+by :sage_root:`src/bin/sage-env` after Sage has set its
 environment variables.
 It can be used to override some of the environment variables determined
 by Sage, or it can contain other shell commands like creating

src/doc/en/thematic_tutorials/group_theory.rst

@@ -329,9 +329,7 @@ Creating groups
 
 This is an annotated list of some small well-known permutation groups
 that can be created simply in Sage. You can find more in the source
-code file ::
-
-    SAGE_ROOT/src/sage/groups/perm_gps/permgroup_named.py
+code file :sage_root:`src/sage/groups/perm_gps/permgroup_named.py`.
 
 * ``SymmetricGroup(n)``: All `n!` permutations on `n` symbols.
 * ``DihedralGroup(n)``: Symmetries of an `n`-gon.  Rotations and

src/doc/fr/tutorial/sagetex.rst

@@ -16,7 +16,7 @@ locale) pour plus de détails.
 
 Voici un bref exemple d'utilisation de SageTeX. La documentation
 complète se trouve dans
-:sage_root:`venv/share/texmf/tex/latex/sagetex`, où ``SAGE_ROOT``
+:file:`SAGE_ROOT/venv/share/texmf/tex/latex/sagetex`, où ``SAGE_ROOT``
 désigne le répertoire racine de votre installation Sage. Elle est
 accompagnée d'un fichier exemple et de scripts Python potentiellement
 utiles.
@@ -114,4 +114,4 @@ compilation précédente.)
 SageTeX offre bien d'autres possibilités. Puisque Sage
 comme LaTeX sont des outils complexes et puissants, le mieux est sans
 doute de consulter la documentation complète de SageTeX, qui se trouve
-dans :sage_root:`venv/share/texmf/tex/latex/sagetex`.
+dans :file:`SAGE_ROOT/venv/share/texmf/tex/latex/sagetex`.