gh-40162: Add documentation for packaging SageMath downstream
    
<!-- ^ 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". -->

Using meson. Should hopefully make it easier for downstream maintainers
to get started, so that we might get sage back in Fedora/Ubuntu/...

I don't have any packaging experience myself, so please make
suggestions!

### 📝 Checklist

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

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

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on. For example,
-->
<!-- - #12345: short description why this is a dependency -->
<!-- - #34567: ... -->
    
URL: #40162
Reported by: Tobias Diez
Reviewer(s): Antonio Rojas, Copilot, Dima Pasechnik, Tobias Diez

Author: Release Manager

.vscode/settings.json

@@ -81,12 +81,15 @@
         "pari",
         "prandom",
         "Pynac",
+        "pyproject",
         "rightarrow",
         "sagemath",
         "scalarfield",
+        "sdist",
         "SEEALSO",
         "setminus",
         "smithform",
+        "spkg",
         "subchart",
         "subcharts",
         "subframe",

src/doc/en/developer/downstream.rst

@@ -0,0 +1,102 @@
+=============================
+Packaging SageMath Downstream
+=============================
+
+This document is intended for downstream maintainers (e.g., Linux distribution
+package maintainers) who wish to create redistributable builds of Sage.
+
+.. contents::
+   :local:
+   :depth: 2
+
+Dependencies
+============
+
+SageMath relies on a broad set of Python and system libraries. These must be
+provided by the downstream distribution. The definitive list of dependencies is
+found in `pyproject.toml <https://github.com/sagemath/sage/blob/develop/pyproject.toml>`_.
+
+These include:
+ - `build-system.requires`: Python packages needed for building SageMath,
+ - `project.dependencies`: Python packages required at runtime,
+ - `project.optional-dependencies`: optional dependencies for additional
+    functionality,
+ - `external.build-requires` and `external.host-requires`: system dependencies
+    needed for building,
+ - `external.dependencies`: system libraries required at runtime.
+
+The `external` section follows `PEP 725 <https://peps.python.org/pep-0725/>`_
+and specifies dependencies in the form of ̀PURLs.
+At the moment, there is no standard interface to translate these PURLs into
+system package names. However, the names should be quite self-explanatory.
+You may also consult the section :ref:`spkg` for a list of Sage's
+dependencies and their corresponding system package names in various
+distributions.
+
+Build Procedure
+===============
+
+1. **Obtain the Source**:
+   Clone the SageMath repository:
+
+   .. code-block:: bash
+
+      git clone https://github.com/sagemath/sage.git
+
+    Alternatively, download the sdist tarball from the
+    `SageMath PyPI project<https://pypi.org/project/sagemath/>`_ or from the
+    `GitHub releases <https://github.com/sagemath/sage/releases>`_.
+
+1. **Prepare the Build Environment**:
+   Ensure a clean and consistent build environment with access to all
+   required system libraries and Python packages.
+
+2. **Build**:
+
+    Create a wheel using the `build` module:
+
+   .. code-block:: bash
+
+      python -m build --wheel --no-isolation
+
+    If you are sure that all dependencies are available, you may also add the
+    `--skip-dependency-check` option.
+    Moreover, if you care about reproducible builds, it is recommended to
+    use `-Cbuild-dir=build` to specify a build directory, see this
+    `Meson-Python issue <https://github.com/mesonbuild/meson-python/issues/671>`_.
+
+3. **Install**:
+
+    The resulting wheel can be installed using
+
+   .. code-block:: bash
+
+      python -m installer --destdir="<pkgdir>" dist/sagemath-*.whl
+
+   where `<pkgdir>` is the directory where you want to install the package
+   (usually a temporary directory for packaging).
+
+4. **Test the Build**:
+
+   Run the Sage tests to ensure functionality:
+
+    .. code-block:: bash
+
+        python -m sage.doctest --all
+
+    However, some tests are known to fail, see :issue:`39872`.
+
+
+If you maintain a downstream package and encounter build issues or patches
+that may benefit others, please consider contributing back by reporting issues
+or opening pull requests on the SageMath GitHub repository.
+
+Other considerations:
+- **Package naming**: Use `sagemath`, or `python-sagemath` if your distribution
+has a convention for Python packages.
+
+Example Downstream Packages
+===========================
+
+- `Arch Linux <https://archlinux.org/packages/extra/x86_64/sagemath>`_
+

src/doc/en/developer/index.rst

@@ -174,6 +174,7 @@ Packaging
    :maxdepth: 2
 
    packaging
+   downstream
    packaging_sage_library
 
 

src/doc/en/developer/packaging_sage_library.rst

@@ -2,7 +2,7 @@
 .. _chapter-modularization:
 
 ===========================================
-Packaging the Sage Library for Distribution
+Modularized Distribution
 ===========================================