diff options
Diffstat (limited to 'docs/userguide')
| -rw-r--r-- | docs/userguide/distribution.rst | 31 | ||||
| -rw-r--r-- | docs/userguide/miscellaneous.rst | 25 |
2 files changed, 16 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..9caa3462 100644 --- a/docs/userguide/miscellaneous.rst +++ b/docs/userguide/miscellaneous.rst @@ -5,25 +5,29 @@ 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 @@ -59,3 +63,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 |