DOC: document how to create source distributions

docs/explanations/design-old.rst

@@ -31,21 +31,6 @@ Python tool (pip_, `pypa/build`_, etc.) to build and install the project.
 ``meson-python`` will build a Python sdist (source distribution) or
 wheel (binary distribution) from Meson_ project.
 
-Source distribution (sdist)
----------------------------
-
-The source distribution is based on ``meson dist``, so make sure all your files
-are included there. In git projects, Meson_ will not include files that are not
-checked into git, keep that in mind when developing. By default, all files
-under version control will be included in the sdist. In order to exclude files,
-use ``export-ignore`` or ``export-subst`` attributes in ``.gitattributes`` (see
-the ``git-archive`` documentation for details; ``meson dist`` uses
-``git-archive`` under the hood).
-
-Local (uncommitted) changes to files that are under version control will be
-included. This is often needed when applying patches, e.g. for build issues
-found during packaging, to work around test failures, to amend the license for
-vendored components in wheels, etc.
 
 Binary distribution (wheels)
 ----------------------------

docs/how-to-guides/sdist.rst

@@ -0,0 +1,54 @@
+.. SPDX-FileCopyrightText: 2024 The meson-python developers
+..
+.. SPDX-License-Identifier: MIT
+
+.. _sdist:
+
+******************************
+Creating a source distribution
+******************************
+
+A source distribution for the project can be created executing
+
+.. code-block:: console
+
+   $ python -m build --sdist .
+
+in the project root folder. This will create a ``.tar.gz`` archive in the
+``dist`` folder in the project root folder. This archive contains the full
+contents of the latest commit in revision control with all revision control
+metadata removed. Uncommitted modifications and files unknown to the revision
+control system are not included.
+
+The source distribution archive is created by adding the required metadata
+files to the archive obtained by executing the ``meson dist --no-tests
+--allow-dirty`` command. To generate a source distribution, ``meson-python``
+must successfully configure the Meson project by running the ``meson setup``
+command. Additional arguments can be passed to ``meson dist`` to alter its
+behavior. Refer to the relevant `Meson documentation`__ and to the
+:ref:`how-to-guides-meson-args` guide for details.
+
+The ``meson dist`` command uses the archival tool of the underlying revision
+control system for creating the archive. This implies that a source
+distribution can only be created for a project versioned in a revision control
+system. Meson supports the Git and Mercurial revision control systems.
+
+Files can be excluded from the source distribution via the relevant mechanism
+provided by the revision control system. When using Git as a revision control
+system, it is possible to exclude files from the source distribution setting
+the ``export-ignore`` attribute. For example, adding a ``.gitattributes``
+files containing
+
+.. code-block:: none
+
+   dev/** export-ignore
+
+would result in the ``dev`` folder to be excluded from the source
+distribution. Refer to the ``git archive`` documentation__ for
+details. Another mechanism to alter the content of the source distribution is
+offered by dist scripts. Refer to the relevant `Meson documentation`__ for
+details.
+
+__ https://mesonbuild.com/Creating-releases.html
+__ https://git-scm.com/docs/git-archive#ATTRIBUTES
+__ https://mesonbuild.com/Reference-manual_builtin_meson.html#mesonadd_dist_script

docs/index.rst

@@ -77,6 +77,7 @@ the use of ``meson-python`` and Meson for Python packaging.
    :hidden:
 
    tutorials/introduction
+   how-to-guides/sdist
    how-to-guides/editable-installs
    how-to-guides/config-settings
    how-to-guides/meson-args