gh-37546: Sphinx ext links for Sage source files

    
<!-- ^ Please provide a concise and informative title. -->
<!-- ^ Don't put issue numbers in the title, do this in the PR
description below. -->
<!-- ^ For example, instead of "Fixes #12345" use "Introduce new method
to calculate 1 + 2". -->
<!-- v Describe your changes below in detail. -->
<!-- v Why is this change required? What problem does it solve? -->
<!-- v If this PR resolves an open issue, please link to it here. For
example, "Fixes #12345". -->

In the documentation, we can now write `` :sage_root:`src/setup.py` ``
or `` :sage_root:`src/doc/en/installation` ``, and it will be formatted
uniformly, and a link to the file in the repository will be created.

- Rebased version of #33756

Fixes #33756.

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->

- [x] The title is concise and informative.
- [ ] The description explains in detail what this PR is about.
- [x] I have linked a relevant issue or discussion.
- [ ] I have created tests covering the changes.
- [ ] I have updated the documentation accordingly.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on. For example,
-->
<!-- - #12345: short description why this is a dependency -->
<!-- - #34567: ... -->
    
URL: #37546
Reported by: Matthias Köppe
Reviewer(s): David Coudert, Kwankyu Lee

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 :file:`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 :file:`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
@@ -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
@@ -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

@@ -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
@@ -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

@@ -128,8 +128,7 @@ support the command ``latex``.
    illustrates LaTeX generation for your object.
 
 #. You can use any macros included in ``amsmath``, ``amssymb``, or
-   ``amsfonts``, or the ones defined in
-   ``SAGE_ROOT/doc/commontex/macros.tex``.
+   ``amsfonts``, or the ones defined in :mod:`sage.misc.latex_macros`.
 
 An example template for a ``_latex_`` method follows. Note that the
 ``.. skip`` line should not be included in your code; it is here to
@@ -162,7 +161,7 @@ Print representation
 ====================
 
 The standard Python printing method is ``__repr__(self)``. In Sage,
-that is for objects that derive from ``SageObject`` (which is
+that is for objects that derive from :class:`SageObject` (which is
 everything in Sage), instead define ``_repr_(self)``. This is
 preferable because if you only define ``_repr_(self)`` and not
 ``__repr__(self)``, then users can rename your object to print however
@@ -171,7 +170,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 +201,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 +220,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 +297,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 +343,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 +537,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 +646,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 :file:`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``.
+  :file:`SAGE_ROOT/src/typings/ppl.pyi` or :file:`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 :file:`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