diff --git a/changelog.d/3372.doc.rst b/changelog.d/3372.doc.rst new file mode 100644 index 0000000000..845c273910 --- /dev/null +++ b/changelog.d/3372.doc.rst @@ -0,0 +1,3 @@ +Consolidated sections about ``sdist`` contents and ``MANIFEST.in`` into a single page. + +Added a simple ``MANIFEST.in`` example. diff --git a/docs/userguide/distribution.rst b/docs/userguide/distribution.rst index db0f1a5f59..d2d0ea8877 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 776f12f691..19908e05ad 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 ` in the +These include all :term:`pure Python modules ` 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 `. -In these situations you can use a ``setuptools`` -:ref:`plugin `, -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 `, 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 `. +.. 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 ` [#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