[Docs] Consolidate sdist and MANIFEST.in info into a single document (#3372)

2 files changed, 48 insertions, 40 deletions

diff --git a/docs/userguide/distribution.rst b/docs/userguide/distribution.rst
index db0f1a5f..d2d0ea88 100644
--- a/docs/userguide/distribution.rst
+++ b/docs/userguide/distribution.rst
@@ -53,37 +53,6 @@ directory.  (And, you could also define sitewide or per-user default versions
 of the ``daily`` alias, so that projects that didn't define their own would
 use the appropriate defaults.)
 
-Generating Source Distributions
--------------------------------
-
-``setuptools`` enhances the distutils' default algorithm for source file
-selection with pluggable endpoints for looking up files to include. If you are
-using a revision control system, and your source distributions only need to
-include files that you're tracking in revision control, use a corresponding
-plugin instead of writing a ``MANIFEST.in`` file. See the section below on
-:ref:`Adding Support for Revision Control Systems` for information on plugins.
-
-If you need to include automatically generated files, or files that are kept in
-an unsupported revision control system, you'll need to create a ``MANIFEST.in``
-file to specify any files that the default file location algorithm doesn't
-catch.  See the distutils documentation for more information on the format of
-the ``MANIFEST.in`` file.
-
-But, be sure to ignore any part of the distutils documentation that deals with
-``MANIFEST`` or how it's generated from ``MANIFEST.in``; setuptools shields you
-from these issues and doesn't work the same way in any case.  Unlike the
-distutils, setuptools regenerates the source distribution manifest file
-every time you build a source distribution, and it builds it inside the
-project's ``.egg-info`` directory, out of the way of your main project
-directory.  You therefore need not worry about whether it is up-to-date or not.
-
-Indeed, because setuptools' approach to determining the contents of a source
-distribution is so much simpler, its ``sdist`` command omits nearly all of
-the options that the distutils' more complex ``sdist`` process requires.  For
-all practical purposes, you'll probably use only the ``--formats`` option, if
-you use any option at all.
-
-
 Making "Official" (Non-Snapshot) Releases
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/userguide/miscellaneous.rst b/docs/userguide/miscellaneous.rst
index 776f12f6..19908e05 100644
--- a/docs/userguide/miscellaneous.rst
+++ b/docs/userguide/miscellaneous.rst
@@ -5,30 +5,66 @@ Controlling files in the distribution
 
 For the most common use cases, ``setuptools`` will automatically find out which
 files are necessary for distributing the package.
-This includes all :term:`pure Python modules <Pure Module>` in the
+These include all :term:`pure Python modules <Pure Module>` in the
 ``py_modules`` or ``packages`` configuration, and the C sources (but not C
-headers) listed as part of extensions when creating a :term:`Source
-Distribution (or "sdist")`.
+headers) listed as part of extensions when creating a :term:`source
+distribution (or "sdist")`.
 
 However, when building more complex packages (e.g. packages that include
 non-Python files, or that need to use custom C headers), you might find that
 not all files present in your project folder are included in package
 :term:`distribution archive <Distribution Package>`.
 
-In these situations you can use a ``setuptools``
-:ref:`plugin <Adding Support for Revision Control Systems>`,
-such as :pypi:`setuptools-scm` or :pypi:`setuptools-svn` to automatically
-include all files tracked by your Revision Control System into the ``sdist``.
+If you are using a :wiki:`Revision Control System`, such as git_ or mercurial_,
+and your source distributions only need to include files that you're
+tracking in revision control, you can use a ``setuptools`` :ref:`plugin <Adding
+Support for Revision Control Systems>`, such as :pypi:`setuptools-scm` or
+:pypi:`setuptools-svn` to automatically include all tracked files into the ``sdist``.
 
 .. _Using MANIFEST.in:
 
-Alternatively, if you need finer control, you can add a ``MANIFEST.in`` file at
-the root of your project.
+Alternatively, if you need finer control over the files (e.g. you don't want to
+distribute :wiki:`CI/CD`-related files) or you need automatically generated files,
+you can add a ``MANIFEST.in`` file at the root of your project,
+to specify any files that the default file location algorithm doesn't catch.
+
 This file contains instructions that tell ``setuptools`` which files exactly
 should be part of the ``sdist`` (or not).
 A comprehensive guide to ``MANIFEST.in`` syntax is available at the
 :doc:`PyPA's Packaging User Guide <PyPUG:guides/using-manifest-in>`.
 
+.. attention::
+   Please note that ``setuptools`` supports the ``MANIFEST.in``,
+   and not ``MANIFEST`` (no extension). Any documentation, tutorial or example
+   that recommends using ``MANIFEST`` (no extension) is likely outdated.
+
+.. tip::
+   The ``MANIFEST.in`` file contains commands that allow you to discover and
+   manipulate lists of files. There are many commands that can be used with
+   different objectives, but you should try to not make your ``MANIFEST.in``
+   file too fine grained.
+
+   A good idea is to start with a ``graft`` command (to add all
+   files inside a set of directories) and then fine tune the file selection
+   by removing the excess or adding isolated files.
+
+An example of ``MANIFEST.in`` for a simple project that organized according to a
+:ref:`src-layout` is:
+
+.. code-block:: bash
+
+   # MANIFEST.in -- just for illustration
+   graft src
+   graft tests
+   graft docs
+   # `-> adds all files inside a directory
+
+   include tox.ini
+   # `-> matches file paths relative to the root of the project
+
+   global-exclude *~ *.py[cod] *.so
+   # `-> matches file names (regardless of directory)
+
 Once the correct files are present in the ``sdist``, they can then be used by
 binary extensions during the build process, or included in the final
 :term:`wheel <Wheel>` [#build-process]_ if you configure ``setuptools`` with
@@ -59,3 +95,6 @@ binary extensions during the build process, or included in the final
    and is ready to be unpacked into a running installation of Python or
    :term:`Virtual Environment`.
    Therefore it only contains items that are required during runtime.
+
+.. _git: https://git-scm.com
+.. _mercurial: https://www.mercurial-scm.org