git grep -l -E "SAGE_ROOT/[^lu]" src/doc | xargs sed -i.bak 's,`SAGE_ROOT/\([^]*\)`,:sage_root:\1`,g'

Author: Matthias Koeppe

src/doc/de/tutorial/sagetex.rst

@@ -15,7 +15,7 @@ Tutorial und den Abschnitt "Make SageTeX known to TeX" des `Sage installation gu
 Installationsanleitung führen) um weitere Informationen zu erhalten.
 
 Hier stellen wir ein sehr kurzes Beispiel vor wie man SageTeX nutzt.
-Die komplette Dokumentation finden Sie unter ``SAGE_ROOT/venv/share/texmf/tex/latex/sagetex``,
+Die komplette Dokumentation finden Sie unter :sage_root:`venv/share/texmf/tex/latex/sagetex`,
 wobei ``SAGE_ROOT`` das Installationsverzeichnis von Sage ist. Dieses Verzeichnis
 enthält die Dokumentation, eine Beispieldatei und einige nützliche Python Skripte.
 
@@ -103,4 +103,4 @@ an den Sage Befehlen in Ihrem Dokument vorgenommen haben.
 
 Es gibt noch viel mehr über SageTeX zu sagen, aber da sowohl Sage alsauch
 LaTeX komplexe und mächtige Werkzeuge sind, sollten Sie die Dokumentation
-über SageTeX in ``SAGE_ROOT/venv/share/texmf/tex/latex/sagetex`` lesen.
+über SageTeX in :sage_root:`venv/share/texmf/tex/latex/sagetex` lesen.

src/doc/en/developer/coding_basics.rst

@@ -123,7 +123,7 @@ of several different types of polynomial rings.
 
 If you want to create a new directory (`package
 <https://docs.python.org/3/tutorial/modules.html#packages>`_) in the
-Sage library ``SAGE_ROOT/src/sage`` (say, ``measure_theory``), that
+Sage library :sage_root:`src/sage` (say, ``measure_theory``), that
 directory will usually contain an empty file ``__init__.py``, which
 marks the directory as an ordinary package (see
 :ref:`section_namespace_packages`), and also a file ``all.py``,
@@ -141,7 +141,7 @@ framework::
     lazy_import('sage.measure_theory.borel_measure', 'BorelMeasure')
     lazy_import('sage.measure_theory.banach_tarski', 'BanachTarskiParadox')
 
-Then in the file ``SAGE_ROOT/src/sage/all.py``, add a line ::
+Then in the file :sage_root:`src/sage/all.py`, add a line ::
 
     from sage.measure_theory.all import *
 
@@ -176,16 +176,16 @@ included in one of the following places:
 
 - Older code in the Sage library accesses
   the package data in more direct ways. For example,
-  ``SAGE_ROOT/src/sage/interfaces/maxima.py`` uses the file
-  ``SAGE_ROOT/src/sage/interfaces/maxima.lisp`` at runtime, so it
+  :sage_root:`src/sage/interfaces/maxima.py` uses the file
+  :sage_root:`src/sage/interfaces/maxima.lisp` at runtime, so it
   refers to it as::
 
     os.path.join(os.path.dirname(__file__), 'sage-maxima.lisp')
 
-- In an appropriate subdirectory of ``SAGE_ROOT/src/sage/ext_data/``.
+- In an appropriate subdirectory of :sage_root:`src/sage/ext_data/`.
   (At runtime, it is then available in the directory indicated by
   ``SAGE_EXTCODE``).  For example, if ``file`` is placed in
-  ``SAGE_ROOT/src/sage/ext_data/directory/`` it can be accessed with ::
+  :sage_root:`src/sage/ext_data/directory/` it can be accessed with ::
 
     from sage.env import SAGE_EXTCODE
     file = os.path.join(SAGE_EXTCODE, 'directory', 'file')
@@ -194,7 +194,7 @@ included in one of the following places:
 
 In all cases, the files must be listed (explicitly or via wildcards) in
 the section ``options.package_data`` of the file
-``SAGE_ROOT/pkgs/sagemath-standard/setup.cfg.m4`` (or the corresponding
+:sage_root:`pkgs/sagemath-standard/setup.cfg.m4` (or the corresponding
 file of another distribution).
 
 Large data files should not be added to the Sage source tree. Instead, it
@@ -270,7 +270,7 @@ The top of each Sage code file should follow this format::
     #                  https://www.gnu.org/licenses/
     # ****************************************************************************
 
-As an example, see ``SAGE_ROOT/src/sage/rings/integer.pyx``, which contains the
+As an example, see :sage_root:`src/sage/rings/integer.pyx`, which contains the
 implementation for `\ZZ`. The names of the people who made major contributions
 to the file appear in the ``AUTHORS`` section. You can add your name to the
 list if you belong to the people, but refrain from being verbose in the
@@ -919,7 +919,7 @@ LaTeX-formatted ``\\Bold{Z}`` in the html manual, and as ``Z`` in the
 interactive help. Other examples: ``\\GF{q}`` (`\GF{q}`) and ``\\Zmod{p}``
 (`\Zmod{p}`).
 
-See the file ``SAGE_ROOT/src/sage/misc/latex_macros.py`` for a full list and
+See the file :sage_root:`src/sage/misc/latex_macros.py` for a full list and
 for details about how to add more macros.
 
 .. _section-doctest-writing:
@@ -968,13 +968,13 @@ written.
 
      Note that **TestSuites** are an automatic way to generate some of these
      tests in specific situations. See
-     ``SAGE_ROOT/src/sage/misc/sage_unittest.py``.
+     :sage_root:`src/sage/misc/sage_unittest.py`.
 
 **The syntax:**
 
 - **Environment:** doctests should work if you copy/paste them in Sage's
   interactive console. For example, the function ``AA()`` in the file
-  ``SAGE_ROOT/src/sage/algebras/steenrod/steenrod_algebra.py`` includes an
+  :sage_root:`src/sage/algebras/steenrod/steenrod_algebra.py` includes an
   EXAMPLES block containing the following::
 
     sage: from sage.algebras.steenrod.steenrod_algebra import AA as A
@@ -1001,7 +1001,7 @@ written.
 - **Writing files:** If a test outputs to a file, the file should be a
   temporary file.  Use :func:`tmp_filename` to get a temporary filename, or
   :func:`tmp_dir` to get a temporary directory. An example from
-  ``SAGE_ROOT/src/sage/plot/graphics.py``)::
+  :sage_root:`src/sage/plot/graphics.py`)::
 
       sage: plot(x^2 - 5, (x, 0, 5), ymin=0).save(tmp_filename(ext='.png'))
 
@@ -1445,14 +1445,14 @@ put ``.. linkall`` anywhere in the file, on a line by itself.  (For
 clarity, it might be best to put it near the top of the file.)  Then
 ``sage -t`` will act as if there were a ``.. link`` before each
 verbatim environment.  The file
-``SAGE_ROOT/src/doc/en/tutorial/interfaces.rst`` contains a
+:sage_root:`src/doc/en/tutorial/interfaces.rst` contains a
 ``.. linkall`` directive, for example.
 
 You can also put ``.. skip`` right before a verbatim environment to
 have that example skipped when testing the file.  This goes in the
 same place as the ``.. link`` in the previous example.
 
-See the files in ``SAGE_ROOT/src/doc/en/tutorial/`` for many
+See the files in :sage_root:`src/doc/en/tutorial/` for many
 examples of how to include automated testing in reST documentation for
 Sage.
 

src/doc/en/developer/coding_in_other.rst

@@ -639,7 +639,7 @@ asynchronous because it derives from the Sage class ``Expect``, which
 handles the communication between Sage and the external process.
 
 For example, here is part of the file
-``SAGE_ROOT/src/sage/interfaces/octave.py``, which
+:sage_root:`src/sage/interfaces/octave.py`, which
 defines an interface between Sage and Octave, an open source program
 for doing numerical computations, among other things:
 
@@ -751,5 +751,5 @@ documented.
 
 These are only excerpts from ``octave.py``; check that file for more
 definitions and examples. Look at other files in the directory
-``SAGE_ROOT/src/sage/interfaces/`` for examples of interfaces to other
+:sage_root:`src/sage/interfaces/` for examples of interfaces to other
 software packages.

src/doc/en/developer/coding_in_python.rst

@@ -129,7 +129,7 @@ support the command ``latex``.
 
 #. You can use any macros included in ``amsmath``, ``amssymb``, or
    ``amsfonts``, or the ones defined in
-   ``SAGE_ROOT/doc/commontex/macros.tex``.
+   :sage_root:`doc/commontex/macros.tex`.
 
 An example template for a ``_latex_`` method follows. Note that the
 ``.. skip`` line should not be included in your code; it is here to
@@ -171,7 +171,7 @@ the context.
 
 Here is an example of the ``_latex_`` and ``_repr_`` functions for the
 ``Pi`` class. It is from the file
-``SAGE_ROOT/src/sage/symbolic/constants.py``:
+:sage_root:`src/sage/symbolic/constants.py`:
 
 .. CODE-BLOCK:: python
 
@@ -202,7 +202,7 @@ matrix over a ring `R`. Then the Sage function ``matrix`` will work
 for this object.
 
 The following is from
-``SAGE_ROOT/src/sage/graphs/generic_graph.py``:
+:sage_root:`src/sage/graphs/generic_graph.py`:
 
 .. CODE-BLOCK:: python
 
@@ -221,7 +221,7 @@ The following is from
 Similarly, provide a ``_vector_`` method for an object that can be
 coerced to a vector over a ring `R`. Then the Sage function ``vector``
 will work for this object. The following is from the file
-``SAGE_ROOT/src/sage/modules/free_module_element.pyx``:
+:sage_root:`src/sage/modules/free_module_element.pyx`:
 
 .. CODE-BLOCK:: python
 
@@ -298,11 +298,11 @@ creates the file ``foo.sage.py``.
 
 The following files are relevant to preparsing in Sage:
 
-#. ``SAGE_ROOT/src/bin/sage``
+#. :sage_root:`src/bin/sage`
 
-#. ``SAGE_ROOT/src/bin/sage-preparse``
+#. :sage_root:`src/bin/sage-preparse`
 
-#. ``SAGE_ROOT/src/sage/repl/preparse.py``
+#. :sage_root:`src/sage/repl/preparse.py`
 
 In particular, the file ``preparse.py`` contains the Sage preparser
 code.
@@ -344,7 +344,7 @@ scope variable.
 
 Certain objects, e.g. matrices, may start out mutable and become
 immutable later. See the file
-``SAGE_ROOT/src/sage/structure/mutability.py``.
+:sage_root:`src/sage/structure/mutability.py`.
 
 
 The  __hash__ special method
@@ -538,15 +538,15 @@ large third-party modules. See also :ref:`section_dependencies_distributions`
 for a discussion of imports from the viewpoint of modularization.
 
 First, you must avoid circular imports. For example, suppose that the
-file ``SAGE_ROOT/src/sage/algebras/steenrod_algebra.py``
+file :sage_root:`src/sage/algebras/steenrod_algebra.py`
 started with a line:
 
 .. CODE-BLOCK:: python
 
     from sage.sage.algebras.steenrod_algebra_bases import *
 
 and that the file
-``SAGE_ROOT/src/sage/algebras/steenrod_algebra_bases.py``
+:sage_root:`src/sage/algebras/steenrod_algebra_bases.py`
 started with a line:
 
 .. CODE-BLOCK:: python
@@ -647,17 +647,17 @@ When importing from other Python libraries that do not provide sufficient typing
 information, it is possible to augment the library's typing information for
 the purposes of typechecking the Sage library:
 
-- Create typestub files and place them in the directory ``SAGE_ROOT/src/typings``.
+- Create typestub files and place them in the directory :sage_root:`src/typings`.
   For example, the distribution **pplpy** provides the top-level package :mod:`ppl`,
   which publishes no typing information. We can create a typestub file
-  ``SAGE_ROOT/src/typings/ppl.pyi`` or ``SAGE_ROOT/src/typings/ppl/__init__.pyi``.
+  :sage_root:`src/typings/ppl.pyi` or :sage_root:`src/typings/ppl/__init__.pyi`.
 
 - When these typestub files are working well, it is preferable from the viewpoint
   of the Sage project that they are "upstreamed", i.e., contributed to the
   project that maintains the library. If a new version of the upstream library
   becomes available that provides the necessary typing information, we can
   update the package in the Sage distribution and remove the typestub files again
-  from ``SAGE_ROOT/src/typings``.
+  from :sage_root:`src/typings`.
 
 - As a fallback, when neither adding typing annotations to source files
   nor adding typestub files is welcomed by the upstream project, it is possible

src/doc/en/developer/doctesting.rst

@@ -499,7 +499,7 @@ Parallel testing the whole Sage library
 =======================================
 
 The main Sage library resides in the directory
-``SAGE_ROOT/src/``. We can use the syntax described above
+:sage_root:`src/`. We can use the syntax described above
 to doctest the main library using multiple threads. When doing release
 management or patching the main Sage library, a release manager would
 parallel test the library using 10 threads with the following command::
@@ -538,22 +538,22 @@ The differences are:
   set of tests. First the Sage standard documentation is tested,
   i.e. the documentation that resides in
 
-  * ``SAGE_ROOT/src/doc/common``
-  * ``SAGE_ROOT/src/doc/en``
-  * ``SAGE_ROOT/src/doc/fr``
+  * :sage_root:`src/doc/common`
+  * :sage_root:`src/doc/en`
+  * :sage_root:`src/doc/fr`
 
   Finally, the commands doctest the Sage library. For more details on
-  these command, see the file ``SAGE_ROOT/Makefile``.
+  these command, see the file :sage_root:`Makefile`.
 
 * ``make testlong`` --- This command doctests the standard
   documentation:
 
-  * ``SAGE_ROOT/src/doc/common``
-  * ``SAGE_ROOT/src/doc/en``
-  * ``SAGE_ROOT/src/doc/fr``
+  * :sage_root:`src/doc/common`
+  * :sage_root:`src/doc/en`
+  * :sage_root:`src/doc/fr`
 
   and then the Sage library. Doctesting is run with the optional
-  argument ``--long``. See the file ``SAGE_ROOT/Makefile`` for further
+  argument ``--long``. See the file :sage_root:`Makefile` for further
   details.
 
 * ``make ptest`` --- Similar to the commands ``make test`` and ``make

src/doc/en/developer/packaging.rst

@@ -9,9 +9,9 @@ Packaging Third-Party Code for Sage
 One of the mottoes of the Sage project is to not reinvent the wheel: If
 an algorithm is already implemented in a well-tested library then
 consider incorporating that library into Sage. The current list of
-available packages are the subdirectories of ``SAGE_ROOT/build/pkgs/``.
+available packages are the subdirectories of :sage_root:`build/pkgs/`.
 The installation of packages is done through a bash script located in
-``SAGE_ROOT/build/bin/sage-spkg``. This script is typically invoked by
+:sage_root:`build/bin/sage-spkg`. This script is typically invoked by
 giving the command::
 
     [alice@localhost sage]$ sage -i <options> <package name>...
@@ -25,7 +25,7 @@ options can be:
 - -d: only download the package
 
 The section :ref:`section-directory-structure` describes the structure
-of each individual package in ``SAGE_ROOT/build/pkgs``. In section
+of each individual package in :sage_root:`build/pkgs`. In section
 :ref:`section-manual-build` we see how you can install and test a new
 spkg that you or someone else wrote. Finally,
 :ref:`section-inclusion-procedure` explains how to submit a new package
@@ -168,7 +168,7 @@ 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>``
+   :sage_root:`build/pkgs/<package>`, where you replace ``<package>``
    with a 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
@@ -177,7 +177,7 @@ Third-party packages in Sage consist of two parts:
 
 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 :sage_root:`upstream` during the installation
 process). To package it in Sage, we create a subdirectory containing as
 a minimum the following files:
 
@@ -336,7 +336,7 @@ Likewise for :envvar:`CXXFLAGS`, :envvar:`FCFLAGS`, and :envvar:`F77FLAGS`.
     In more detail: ``sage-bootstrap-python`` runs a version of Python
     pre-installed on the machine, which is a build prerequisite of Sage.
     Note that ``sage-bootstrap-python`` accepts a wide range of Python
-    versions, Python >= 2.6 and >= 3.4, see ``SAGE_ROOT/build/tox.ini``
+    versions, Python >= 2.6 and >= 3.4, see :sage_root:`build/tox.ini`
     for details.  You should only use ``sage-bootstrap-python`` for
     installation tasks that must be able to run before Sage has made
     ``python3`` available.  It must not be used for running ``pip`` or
@@ -1226,7 +1226,7 @@ or::
     [alice@localhost sage]$ sage -f -c package_name
 
 If all went fine, open a PR with the code under
-``SAGE_ROOT/build/pkgs``.
+:sage_root:`build/pkgs`.
 
 
 .. _section-spkg-patching:
@@ -1483,7 +1483,7 @@ License information
 -------------------
 
 License information for a package needs to be put both in its
-``SPKG.rst`` file and in the file ``SAGE_ROOT/COPYING.txt``.
+``SPKG.rst`` file and in the file :sage_root:`COPYING.txt`.
 Whenever upgrading a package, check whether the license changed between
 versions.