diff --git a/src/doc/de/tutorial/sagetex.rst b/src/doc/de/tutorial/sagetex.rst index 37780eb6cf2..ac64fe25ec6 100644 --- a/src/doc/de/tutorial/sagetex.rst +++ b/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. diff --git a/src/doc/en/developer/coding_basics.rst b/src/doc/en/developer/coding_basics.rst index 880efb5cee0..eb10c552224 100644 --- a/src/doc/en/developer/coding_basics.rst +++ b/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 `_) 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 ``[tool.setuptools.package-data]`` of the file -``SAGE_ROOT/pkgs/sagemath-standard/pyproject.toml.m4`` (or the corresponding +:sage_root:`SAGE_ROOT/pkgs/sagemath-standard/pyproject.toml.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. diff --git a/src/doc/en/developer/coding_in_other.rst b/src/doc/en/developer/coding_in_other.rst index 54ff5d3b772..8e046a1eea3 100644 --- a/src/doc/en/developer/coding_in_other.rst +++ b/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. diff --git a/src/doc/en/developer/coding_in_python.rst b/src/doc/en/developer/coding_in_python.rst index aabdecb2d9e..3242691595e 100644 --- a/src/doc/en/developer/coding_in_python.rst +++ b/src/doc/en/developer/coding_in_python.rst @@ -129,8 +129,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 @@ -163,7 +162,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 @@ -172,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 @@ -203,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 @@ -222,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 @@ -299,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. @@ -345,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 @@ -539,7 +538,7 @@ 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 @@ -547,7 +546,7 @@ started with a line: 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 @@ -648,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 :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 diff --git a/src/doc/en/developer/doctesting.rst b/src/doc/en/developer/doctesting.rst index e6324640ca1..75cc659934f 100644 --- a/src/doc/en/developer/doctesting.rst +++ b/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 diff --git a/src/doc/en/developer/packaging.rst b/src/doc/en/developer/packaging.rst index f627e969ee4..ef1f0d49b94 100644 --- a/src/doc/en/developer/packaging.rst +++ b/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 ... @@ -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,8 +168,8 @@ Third-party packages in Sage consist of two parts: instead. #. The build scripts and associated files are in a subdirectory - ``SAGE_ROOT/build/pkgs/``, where you replace ```` - 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 @@ -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 :file:`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 @@ -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". @@ -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. diff --git a/src/doc/en/developer/packaging_sage_library.rst b/src/doc/en/developer/packaging_sage_library.rst index 9a29442d624..9b688cf2967 100644 --- a/src/doc/en/developer/packaging_sage_library.rst +++ b/src/doc/en/developer/packaging_sage_library.rst @@ -12,14 +12,14 @@ Modules, packages, distribution packages The Sage library consists of a large number of Python modules, organized into a hierarchical set of packages that fill the namespace :mod:`sage`. All source files are located in a subdirectory of the -directory ``SAGE_ROOT/src/sage/``. +directory :sage_root:`src/sage/`. For example, -- the file ``SAGE_ROOT/src/sage/coding/code_bounds.py`` provides the +- the file :sage_root:`src/sage/coding/code_bounds.py` provides the module :mod:`sage.coding.code_bounds`; -- the directory containing this file, ``SAGE_ROOT/src/sage/coding/``, +- the directory containing this file, :sage_root:`src/sage/coding/`, thus provides the package :mod:`sage.coding`. There is another notion of "package" in Python, the **distribution @@ -28,7 +28,7 @@ package"). Currently, the entire Sage library is provided by a single distribution, `sagemath-standard `_, which is generated from the directory -``SAGE_ROOT/pkgs/sagemath-standard``. +:sage_root:`pkgs/sagemath-standard`. Note that the distribution name is not required to be a Python identifier. In fact, using dashes (``-``) is preferred to underscores in @@ -129,7 +129,7 @@ Source directories of distribution packages The development of the Sage library uses a monorepo strategy for all distribution packages that fill the :mod:`sage.*` namespace. This means that the source trees of these distributions are included in a -single ``git`` repository, in a subdirectory of ``SAGE_ROOT/pkgs``. +single ``git`` repository, in a subdirectory of :sage_root:`pkgs`. All these distribution packages have matching version numbers. From the viewpoint of a single distribution, this means that sometimes @@ -137,10 +137,10 @@ there will be a new release of some distribution where the only thing changing is the version number. The source directory of a distribution package, such as -``SAGE_ROOT/pkgs/sagemath-standard``, contains the following files: +:sage_root:`pkgs/sagemath-standard`, contains the following files: - ``sage`` -- a relative symbolic link to the monolithic Sage library - source tree ``SAGE_ROOT/src/sage/`` + source tree :sage_root:`src/sage/` - `MANIFEST.in `_ -- controls which files and directories of the @@ -182,7 +182,7 @@ The source directory of a distribution package, such as - ``README.rst`` -- a description of the distribution - ``LICENSE.txt`` -- relative symbolic link to the same files - in ``SAGE_ROOT/src`` + in :sage_root:`src` - ``VERSION.txt`` -- package version. This file is updated by the release manager by running the ``sage-update-version`` script. @@ -213,15 +213,15 @@ The source directory of a distribution package, such as - ``tox.ini`` -- configuration for testing with `tox `_ -The technique of using symbolic links pointing into ``SAGE_ROOT/src`` -has allowed the modularization effort to keep the ``SAGE_ROOT/src`` +The technique of using symbolic links pointing into :sage_root:`src` +has allowed the modularization effort to keep the :sage_root:`src` tree monolithic: Modularization has been happening behind the scenes and will not change where Sage developers find the source files. Some of these files may actually be generated from source files with suffix ``.m4`` by the -``SAGE_ROOT/bootstrap`` script via the ``m4`` macro processor. +:sage_root:`bootstrap` script via the ``m4`` macro processor. -For every distribution package, there is also a subdirectory of ``SAGE_ROOT/build/pkgs/``, +For every distribution package, there is also a subdirectory of :sage_root:`build/pkgs/`, which contains the build infrastructure that is specific to Sage-the-distribution. Note that these subdirectories follows a different naming convention, using underscores instead of dashes, see :ref:`section-directory-structure`. @@ -680,17 +680,17 @@ these wheels and our distribution to be tested. This is where `tox `_ comes into play: It is the standard Python tool for creating disposable virtual environments for testing. Every distribution in -``SAGE_ROOT/pkgs/`` provides a configuration file ``tox.ini``. +:sage_root:`pkgs/` provides a configuration file ``tox.ini``. Following the comments in the file -``SAGE_ROOT/pkgs/sagemath-standard/tox.ini``, we can try the following +:sage_root:`pkgs/sagemath-standard/tox.ini`, we can try the following command:: $ ./bootstrap && ./sage -sh -c '(cd pkgs/sagemath-standard && SAGE_NUM_THREADS=16 tox -v -v -v -e sagepython-sagewheels-nopypi)' This command does not make any changes to the normal installation of Sage. The virtual environment is created in a subdirectory of -``SAGE_ROOT/pkgs/sagemath-standard/.tox/``. After the command +:file:`SAGE_ROOT/pkgs/sagemath-standard/.tox/`. After the command finishes, we can start the separate installation of the Sage library in its virtual environment:: diff --git a/src/doc/en/developer/portability_testing.rst b/src/doc/en/developer/portability_testing.rst index b40f0d3948b..c7925b3392a 100644 --- a/src/doc/en/developer/portability_testing.rst +++ b/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 - `_ - (which calls `$SAGE_ROOT/.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 - `_. +- :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 - `_); + :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 `_ -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 diff --git a/src/doc/en/developer/sage_manuals.rst b/src/doc/en/developer/sage_manuals.rst index 986d3c83a75..13f6a3da94a 100644 --- a/src/doc/en/developer/sage_manuals.rst +++ b/src/doc/en/developer/sage_manuals.rst @@ -18,24 +18,24 @@ Sage's manuals are written in `ReST `_ - Files * - `Tutorial <../tutorial/index.html>`_ - - ``SAGE_ROOT/src/doc/en/tutorial`` + - :sage_root:`src/doc/en/tutorial` * - `Developer's guide <../developer/index.html>`_ - - ``SAGE_ROOT/src/doc/en/developer`` + - :sage_root:`src/doc/en/developer` * - `Constructions <../constructions/index.html>`_ - - ``SAGE_ROOT/src/doc/en/constructions`` + - :sage_root:`src/doc/en/constructions` * - `Installation guide <../installation/index.html>`_ - - ``SAGE_ROOT/src/doc/en/installation`` + - :sage_root:`src/doc/en/installation` * - `Reference manual <../reference/index.html>`_ - - ``SAGE_ROOT/src/doc/en/reference`` + - :sage_root:`src/doc/en/reference` (most of it is generated from the source code) - Additionally, more specialized manuals can be found under - ``SAGE_ROOT/src/doc/en``. + :sage_root:`src/doc/en`. - Some documents have been **translated** into other languages. In order to access them, change ``en/`` into ``fr/``, ``es/``, ``de/``... See :ref:`section-manuals-names`. @@ -46,12 +46,12 @@ Editing the documentation ========================= After modifying some files in the Sage tutorial -(``SAGE_ROOT/src/doc/en/tutorial/``), you will want to visualize the result. In +(:sage_root:`src/doc/en/tutorial/`), you will want to visualize the result. In order to build a **html** version of this document, type:: sage --docbuild tutorial html -You can now open ``SAGE_ROOT/local/share/doc/sage/html/en/tutorial/index.html`` in +You can now open :file:`SAGE_ROOT/local/share/doc/sage/html/en/tutorial/index.html` in your web browser. - Do you want to **add a new file** to the documentation? :ref:`Click here @@ -177,9 +177,13 @@ by Sage, you can link toward it without specifying its full path: :header-rows: 0 * - GitHub issue - - ``issue:`17596``` + - ``:issue:`17596``` - :issue:`17596` + * - Sage repository file or directory + - ``:sage_root:`src/doc/en``` + - :sage_root:`src/doc/en` + * - Wikipedia - ``:wikipedia:`Sage_(mathematics_software)``` - :wikipedia:`Sage_(mathematics_software)` @@ -283,7 +287,7 @@ Adding a new file If you added a new file to Sage (e.g. ``sage/matroids/my_algorithm.py``) and you want its content to appear in the reference manual, you have to add its name to -the file ``SAGE_ROOT/src/doc/en/reference/matroids/index.rst``. Replace +the file :sage_root:`src/doc/en/reference/matroids/index.rst`. Replace 'matroids' with whatever fits your case. **The combinat/ folder:** if your new file belongs to a subdirectory of combinat/ the @@ -293,7 +297,7 @@ procedure is different: directory that contains your file. * Add your file to the index contained in - ``SAGE_ROOT/src/doc/en/reference/combinat/module_list.rst``. + :sage_root:`src/doc/en/reference/combinat/module_list.rst`. .. _section-documentation-conditional: @@ -331,7 +335,7 @@ Building the manuals All of the Sage manuals are built using the ``sage --docbuild`` script. The content of the ``sage --docbuild`` script is defined in -``SAGE_ROOT/src/sage_docbuild/__init__.py``. It is a thin wrapper around +:sage_root:`src/sage_docbuild/__init__.py`. It is a thin wrapper around the ``sphinx-build`` script which does all of the real work. It is designed to be a replacement for the default Makefiles generated by the ``sphinx-quickstart`` script. The general form of the command diff --git a/src/doc/en/developer/tools.rst b/src/doc/en/developer/tools.rst index 3bc3aad8093..28b94349aaf 100644 --- a/src/doc/en/developer/tools.rst +++ b/src/doc/en/developer/tools.rst @@ -21,19 +21,19 @@ Sage includes tox as a standard package and uses it for three purposes: - For portability testing of the Sage distribution, as we explain in :ref:`chapter-portability_testing`. This is configured in the file - ``SAGE_ROOT/tox.ini``. + :sage_root:`tox.ini`. - For testing modularized distributions of the Sage library. This is configured - in ``tox.ini`` files in subdirectories of ``SAGE_ROOT/pkgs/``, such as - ``SAGE_ROOT/pkgs/sagemath-standard/tox.ini``. Each distribution's configuration + in ``tox.ini`` files in subdirectories of :sage_root:`pkgs/`, such as + :sage_root:`pkgs/sagemath-standard/tox.ini`. Each distribution's configuration defines tox environments for testing the distribution with different Python versions and different ways how the dependencies are provided. We explain this in :ref:`chapter-modularization`. - As an entry point for testing and linting of the Sage library, as we describe below. - This is configured in the file ``SAGE_ROOT/src/tox.ini``. + This is configured in the file :sage_root:`src/tox.ini`. -The tox configuration ``SAGE_ROOT/src/tox.ini`` can be invoked by using the command +The tox configuration :sage_root:`src/tox.ini` can be invoked by using the command ``./sage --tox``. (If ``tox`` is available in your system installation, you can just type ``tox`` instead.) @@ -97,7 +97,7 @@ for code coverage analysis. If invoked as ``./sage -tox -e coverage.py-html``, additionally a detailed HTML report is generated. -*Configuration:* ``[coverage:run]`` block in ``SAGE_ROOT/src/tox.ini`` +*Configuration:* ``[coverage:run]`` block in :sage_root:`src/tox.ini` *Documentation:* https://coverage.readthedocs.io @@ -259,13 +259,13 @@ or a few related issues:: - Manual: Run ``pycodestyle path/to/the/file.py``. - VS Code: The minimal version of pycodestyle is activated by default in - ``SAGE_ROOT/.vscode/settings.json`` (the corresponding setting is + :sage_root:`.vscode/settings.json` (the corresponding setting is ``"python.linting.pycodestyleEnabled": true``). Note that the ``settings.json`` file is not ignored by Git so be aware to keep it in sync with the Sage repo on GitHub. For further details, see the `official VS Code documentation `__. -*Configuration:* ``[pycodestyle]`` block in ``SAGE_ROOT/src/tox.ini`` +*Configuration:* ``[pycodestyle]`` block in :sage_root:`src/tox.ini` *Documentation:* https://pycodestyle.pycqa.org/en/latest/index.html @@ -303,7 +303,7 @@ Our configuration of relint flags some outdated Python constructions, plain TeX commands when equivalent LaTeX commands are available, common mistakes in documentation markup, and modularization anti-patterns. -*Configuration:* ``SAGE_ROOT/src/.relint.yml`` +*Configuration:* :sage_root:`src/.relint.yml` *Documentation:* https://pypi.org/project/relint/ @@ -336,9 +336,9 @@ Sage defines a configuration for codespell:: *Configuration:* -- ``[testenv:codespell]`` block in ``SAGE_ROOT/src/tox.ini`` +- ``[testenv:codespell]`` block in :sage_root:`src/tox.ini` -- ``SAGE_ROOT/src/.codespell-dictionary.txt`` and ``SAGE_ROOT/src/.codespell-ignore.txt`` +- :sage_root:`src/.codespell-dictionary.txt` and :sage_root:`src/.codespell-ignore.txt` .. _section-tools-pytest: @@ -369,7 +369,7 @@ package :mod:`sage.numerical.backends` and some modules in - VS Code: Install the `Python extension `_ and follow the `offical VS Code documentation `__. -*Configuration:* ``SAGE_ROOT/src/conftest.py`` +*Configuration:* :sage_root:`src/conftest.py` *Documentation:* https://docs.pytest.org/en/stable/index.html @@ -395,7 +395,7 @@ Pyright - VS Code: Install the `Pylance `__ extension. -*Configuration:* ``SAGE_ROOT/pyrightconfig.json`` +*Configuration:* :sage_root:`pyrightconfig.json` *Documentation:* https://github.com/microsoft/pyright#documentation diff --git a/src/doc/en/installation/source.rst b/src/doc/en/installation/source.rst index 6d27e67731d..2ba63eae3e8 100644 --- a/src/doc/en/installation/source.rst +++ b/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 diff --git a/src/doc/en/reference/repl/startup.rst b/src/doc/en/reference/repl/startup.rst index 44ce958d95f..48e4cda756a 100644 --- a/src/doc/en/reference/repl/startup.rst +++ b/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 diff --git a/src/doc/en/thematic_tutorials/group_theory.rst b/src/doc/en/thematic_tutorials/group_theory.rst index dd0afcbef0c..d9ad8e9f00f 100644 --- a/src/doc/en/thematic_tutorials/group_theory.rst +++ b/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 diff --git a/src/doc/en/tutorial/sagetex.rst b/src/doc/en/tutorial/sagetex.rst index e240e4dc277..4aa13c2da1f 100644 --- a/src/doc/en/tutorial/sagetex.rst +++ b/src/doc/en/tutorial/sagetex.rst @@ -12,10 +12,10 @@ An example ---------- Here is a very brief example of using SageTeX. The full documentation -can be found in ``SAGE_ROOT/venv/share/doc/sagetex``, +can be found in :file:`SAGE_ROOT/venv/share/doc/sagetex`, where ``SAGE_ROOT`` is the directory where your Sage installation is located. That directory contains the documentation and an example file. -See ``SAGE_ROOT/venv/share/texmf/tex/latex/sagetex`` for +See :file:`SAGE_ROOT/venv/share/texmf/tex/latex/sagetex` for some possibly useful Python scripts. To see how SageTeX works, follow the directions for installing SageTeX (in @@ -105,7 +105,7 @@ commands in your document. There's a lot more to SageTeX, and since both Sage and LaTeX are complex, powerful tools, it's a good idea to read the documentation for SageTeX, which is in -``SAGE_ROOT/venv/share/doc/sagetex``. +:file:`SAGE_ROOT/venv/share/doc/sagetex`. .. _sec-sagetex_install: @@ -122,7 +122,7 @@ installation aware of it before it will work. The key to this is that TeX needs to be able to find ``sagetex.sty``, which can be found in -``SAGE_ROOT/venv/share/texmf/tex/latex/sagetex/``, where +:file:`SAGE_ROOT/venv/share/texmf/tex/latex/sagetex/`, where ``SAGE_ROOT`` is the directory where you built or installed Sage. If TeX can find ``sagetex.sty``, then SageTeX will work. There are several ways to accomplish this. @@ -169,7 +169,7 @@ ways to accomplish this. which will print out a directory, such as ``/home/drake/texmf`` or ``/Users/drake/Library/texmf``. Copy the ``tex/`` directory from - ``SAGE_ROOT/venv/share/texmf/`` into your home ``texmf`` directory + :file:`SAGE_ROOT/venv/share/texmf/` into your home ``texmf`` directory with a command like .. CODE-BLOCK:: shell-session @@ -225,7 +225,7 @@ SageTeX documentation While not strictly part of installation, it bears mentioning here that the documentation for SageTeX is maintained in -``SAGE_ROOT/venv/share/doc/sagetex/sagetex.pdf``. There is also an +:file:`SAGE_ROOT/venv/share/doc/sagetex/sagetex.pdf`. There is also an example file in the same directory -- see ``example.tex`` and ``example.pdf``, the pre-built result of typesetting that file with LaTeX and Sage. You can also get those files from the `SageTeX page `_. diff --git a/src/doc/fr/tutorial/sagetex.rst b/src/doc/fr/tutorial/sagetex.rst index b17f0ad56f7..b87ccb7769e 100644 --- a/src/doc/fr/tutorial/sagetex.rst +++ b/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`. diff --git a/src/doc/it/faq/faq-general.rst b/src/doc/it/faq/faq-general.rst index 85ea1c1ad38..6b022bdf40a 100644 --- a/src/doc/it/faq/faq-general.rst +++ b/src/doc/it/faq/faq-general.rst @@ -292,7 +292,7 @@ Per scaricare la documentazione standard di Sage in formato HTML o PDF, visita Ogni release di Sage dispone della documentazione completa che costituisce la documentazione standard di Sage. Se hai scaricato un rilascio di Sage in formato binario, la versione HTML della sua documentazione si trova già disponibile nella -cartella ``SAGE_ROOT/src/doc/output/html/``. Nel corso della compilazione da +cartella :sage_root:`src/doc/output/html/`. Nel corso della compilazione da sorgente viene preparata anche la documentazione HTML. Per construire la versione HTML della documentazione, lancia il seguente comando dopo essersi posizionati in ``SAGE_ROOT``:: diff --git a/src/doc/ja/tutorial/sagetex.rst b/src/doc/ja/tutorial/sagetex.rst index dbbdc3ff7bd..974e3a8391b 100644 --- a/src/doc/ja/tutorial/sagetex.rst +++ b/src/doc/ja/tutorial/sagetex.rst @@ -12,8 +12,8 @@ SageTeXパッケージを使うと，Sageによる処理結果をLaTeX文書に ======= ここでは，ごく簡単な例題を通してSageTeXの利用手順を紹介する． -完全な解説ドキュメントと例題ファイルは，ディレクトリ ``SAGE_ROOT/venv/share/doc/sagetex`` に置いてある． -``SAGE_ROOT/venv/share/texmf/tex/latex/sagetex`` にあるPythonスクリプトは何か役に立つ場面があるはずだ． +完全な解説ドキュメントと例題ファイルは，ディレクトリ :file:`SAGE_ROOT/venv/share/doc/sagetex` に置いてある． +:file:`SAGE_ROOT/venv/share/texmf/tex/latex/sagetex` にあるPythonスクリプトは何か役に立つ場面があるはずだ． 以上の ``SAGE_ROOT`` は，Sageをインストールしたディレクトリである． @@ -98,7 +98,7 @@ SageTeXの動作を体験するために，まずSageTeXのインストール手 SageTeXは到底以上で語り尽せるものでなく，SageとLaTeXは共に複雑で強力なツールだ． -``SAGE_ROOT/venv/share/doc/sagetex`` にあるSageTeXのドキュメントを読むことを強くお勧めする． +:file:`SAGE_ROOT/venv/share/doc/sagetex` にあるSageTeXのドキュメントを読むことを強くお勧めする． .. _sec-sagetex_install: @@ -118,7 +118,7 @@ SageTeXはデフォルトでSageにインストールされるが，LaTeX文書 鍵になるのは， TeXが ``sagetex.sty`` を発見できるかどうかである． この ``sagetex.sty`` は， ``SAGE_ROOT`` をSageがビルトあるいはインストールされたディレクトリとすると， -``SAGE_ROOT/venv/share/texmf/tex/latex/sagetex/`` に置かれているはずだ． +:file:`SAGE_ROOT/venv/share/texmf/tex/latex/sagetex/` に置かれているはずだ． TeXが ``sagetex.sty`` を読めるようにしてやらなければ，SageTeXも動作できないのである． これを実現するには何通りかのやり方がある． @@ -163,7 +163,7 @@ TeXが ``sagetex.sty`` を読めるようにしてやらなければ，SageTeX kpsewhich -var-value=TEXMFHOME - を実行する．すると ``/home/drake/texmf`` や ``/Users/drake/Library/texmf`` などと表示されるはずだから， ``SAGE_ROOT/venv/share/texmf/`` 内の ``tex/`` ディレクトリをホームディレクトリの ``texmf`` にコピーするには + を実行する．すると ``/home/drake/texmf`` や ``/Users/drake/Library/texmf`` などと表示されるはずだから， :file:`SAGE_ROOT/venv/share/texmf/` 内の ``tex/`` ディレクトリをホームディレクトリの ``texmf`` にコピーするには :: @@ -210,7 +210,7 @@ SageTeXドキュメント --------------------- 厳密にはSageのインストール一式には含まれないものの，ここで -SageTeXのドキュメントが ``SAGE_ROOT/venv/share/doc/sagetex/sagetex.pdf`` に配置されていることに触れておきたい． +SageTeXのドキュメントが :file:`SAGE_ROOT/venv/share/doc/sagetex/sagetex.pdf` に配置されていることに触れておきたい． 同じディレクトリには例題ファイルと，これをLaTeXとSageTeXによってすでに組版処理した結果も用意されている(``example.tex`` と ``example.pdf`` を参照)． これらのファイルは `SageTeX ページ `_ からダンロードすることもできる． diff --git a/src/doc/pt/tutorial/sagetex.rst b/src/doc/pt/tutorial/sagetex.rst index 8b0c47b6891..c940c3fe08c 100644 --- a/src/doc/pt/tutorial/sagetex.rst +++ b/src/doc/pt/tutorial/sagetex.rst @@ -14,7 +14,7 @@ instalação do Sage `_ Aqui vai um breve exemplo de como usar o SageTeX. A documentação completa pode ser encontrada em -``SAGE_ROOT/venv/share/texmf/tex/latex/sagetex``, onde +:file:`SAGE_ROOT/venv/share/texmf/tex/latex/sagetex`, onde ``SAGE_ROOT`` é o diretório onde se encontra a sua instalação. Esse diretório contém a documentação, um arquivo de exemplo, e alguns scripts em Python possivelmente úteis. @@ -107,4 +107,4 @@ os comandos em Sage em seu documento. Há muito mais sobre o SageTeX, e como tanto o Sage como o LaTeX são ferramentas complexas e poderosas, é uma boa idéia ler a documentação para o SageTeX que se encontra em -``SAGE_ROOT/venv/share/texmf/tex/latex/sagetex``. +:file:`SAGE_ROOT/venv/share/texmf/tex/latex/sagetex`. diff --git a/src/doc/ru/tutorial/sagetex.rst b/src/doc/ru/tutorial/sagetex.rst index 8c930e2de2a..1742ea4ff42 100644 --- a/src/doc/ru/tutorial/sagetex.rst +++ b/src/doc/ru/tutorial/sagetex.rst @@ -12,7 +12,7 @@ SageTeX known to TeX" `Руководства по установке Sage по установке). В этом уроке показан небольшой пример использования SageTeX. Полная документация -находится в ``SAGE_ROOT/venv/share/texmf/tex/latex/sagetex``, где +находится в :file:`SAGE_ROOT/venv/share/texmf/tex/latex/sagetex`, где ``SAGE_ROOT`` - это директория, в которой установлен Sage. Эта папка содержит документацию, файл с примером и полезные скрипты Python. @@ -89,4 +89,4 @@ SageTeX known to TeX" `Руководства по установке Sage SageTeX предлагает много возможностей, и так как Sage и LaTeX являются мощными инструментами, то стоит изучить -``SAGE_ROOT/venv/share/texmf/tex/latex/sagetex``. +:file:`SAGE_ROOT/venv/share/texmf/tex/latex/sagetex`. diff --git a/src/sage/misc/sagedoc.py b/src/sage/misc/sagedoc.py index 58f1d65b13c..6c711c0e3dd 100644 --- a/src/sage/misc/sagedoc.py +++ b/src/sage/misc/sagedoc.py @@ -508,6 +508,7 @@ def process_dollars(s): extlinks = { 'python': (f'https://docs.python.org/release/{pythonversion}/%s', None), 'issue': ('https://github.com/sagemath/sage/issues/%s', 'Issue #%s'), + 'sage_root': ('https://github.com/sagemath/sage/tree/develop/%s', 'SAGE_ROOT/%s'), 'wikipedia': ('https://en.wikipedia.org/wiki/%s', 'Wikipedia article %s'), 'arxiv': ('https://arxiv.org/abs/%s', 'arXiv %s'), 'oeis': ('https://oeis.org/%s', 'OEIS sequence %s'),