From bc618da735a02a1cebb85fd979ccdd317b308276 Mon Sep 17 00:00:00 2001
From: Alexey Kotlyarov
Date: Thu, 17 Mar 2016 16:06:41 +1100
Subject: [PATCH 1/2] Remove CVS and Subversion references in
include_package_data docs
---
docs/setuptools.txt | 96 +++++++++++++++++----------------------------
1 file changed, 35 insertions(+), 61 deletions(-)
diff --git a/docs/setuptools.txt b/docs/setuptools.txt
index 610a0e613d..d267bf2914 100644
--- a/docs/setuptools.txt
+++ b/docs/setuptools.txt
@@ -258,10 +258,9 @@ unless you need the associated ``setuptools`` feature.
``include_package_data``
If set to ``True``, this tells ``setuptools`` to automatically include any
- data files it finds inside your package directories, that are either under
- CVS or Subversion control, or which are specified by your ``MANIFEST.in``
- file. For more information, see the section below on `Including Data
- Files`_.
+ data files it finds inside your package directories that are specified by
+ your ``MANIFEST.in`` file. For more information, see the section below on
+ `Including Data Files`_.
``exclude_package_data``
A dictionary mapping package names to lists of glob patterns that should
@@ -785,17 +784,15 @@ e.g.::
)
This tells setuptools to install any data files it finds in your packages.
-The data files must be under CVS or Subversion control, or else they must be
-specified via the distutils' ``MANIFEST.in`` file. (They can also be tracked
-by another revision control system, using an appropriate plugin. See the
-section below on `Adding Support for Other Revision Control Systems`_ for
-information on how to write such plugins.)
-
-If the data files are not under version control, or are not in a supported
-version control system, or if you want finer-grained control over what files
-are included (for example, if you have documentation files in your package
-directories and want to exclude them from installation), then you can also use
-the ``package_data`` keyword, e.g.::
+The data files must be specified via the distutils' ``MANIFEST.in`` file.
+(They can also be tracked by a revision control system, using an appropriate
+plugin. See the section below on `Adding Support for Revision Control
+Systems`_ for information on how to write such plugins.)
+
+If you want finer-grained control over what files are included (for example,
+if you have documentation files in your package directories and want to exclude
+them from installation), then you can also use the ``package_data`` keyword,
+e.g.::
from setuptools import setup, find_packages
setup(
@@ -853,8 +850,7 @@ converts slashes to appropriate platform-specific separators at build time.
Python 2.4; there is `some documentation for the feature`__ available on the
python.org website. If using the setuptools-specific ``include_package_data``
argument, files specified by ``package_data`` will *not* be automatically
-added to the manifest unless they are tracked by a supported version control
-system, or are listed in the MANIFEST.in file.)
+added to the manifest unless they are listed in the MANIFEST.in file.)
__ http://docs.python.org/dist/node11.html
@@ -887,8 +883,7 @@ included as a result of using ``include_package_data``.
In summary, the three options allow you to:
``include_package_data``
- Accept all data files and directories matched by ``MANIFEST.in`` or found
- in source control.
+ Accept all data files and directories matched by ``MANIFEST.in``.
``package_data``
Specify additional patterns to match files and directories that may or may
@@ -1231,15 +1226,14 @@ Your Project's Dependencies
target audience isn't able to compile packages (e.g. most Windows users)
and your package or some of its dependencies include C code.
-Subversion or CVS Users and Co-Developers
+Revision Control System Users and Co-Developers
Users and co-developers who are tracking your in-development code using
- CVS, Subversion, or some other revision control system should probably read
- this manual's sections regarding such development. Alternately, you may
- wish to create a quick-reference guide containing the tips from this manual
- that apply to your particular situation. For example, if you recommend
- that people use ``setup.py develop`` when tracking your in-development
- code, you should let them know that this needs to be run after every update
- or commit.
+ a revision control system should probably read this manual's sections
+ regarding such development. Alternately, you may wish to create a
+ quick-reference guide containing the tips from this manual that apply to
+ your particular situation. For example, if you recommend that people use
+ ``setup.py develop`` when tracking your in-development code, you should let
+ them know that this needs to be run after every update or commit.
Similarly, if you remove modules or data files from your project, you
should remind them to run ``setup.py clean --all`` and delete any obsolete
@@ -1467,25 +1461,10 @@ use the appropriate defaults.)
Generating Source Distributions
-------------------------------
-``setuptools`` enhances the distutils' default algorithm for source file
-selection, so that all files managed by CVS or Subversion in your project tree
-are included in any source distribution you build. This is a big improvement
-over having to manually write a ``MANIFEST.in`` file and try to keep it in
-sync with your project. So, if you are using CVS or Subversion, and your
-source distributions only need to include files that you're tracking in
-revision control, don't create a ``MANIFEST.in`` file for your project.
-(And, if you already have one, you might consider deleting it the next time
-you would otherwise have to change it.)
-
-(NOTE: other revision control systems besides CVS and Subversion can be
-supported using plugins; see the section below on `Adding Support for Other
-Revision Control Systems`_ for information on how to write such 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.
+If you need to include automatically generated files, 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
@@ -1501,12 +1480,6 @@ 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.
-(By the way, if you're using some other revision control system, you might
-consider creating and publishing a `revision control plugin for setuptools`_.)
-
-
-.. _revision control plugin for setuptools: `Adding Support for Other Revision Control Systems`_
-
Making your package available for EasyInstall
---------------------------------------------
@@ -1687,9 +1660,10 @@ Of course, for this to work, your source distributions must include the C
code generated by Pyrex, as well as your original ``.pyx`` files. This means
that you will probably want to include current ``.c`` files in your revision
control system, rebuilding them whenever you check changes in for the ``.pyx``
-source files. This will ensure that people tracking your project in CVS or
-Subversion will be able to build it even if they don't have Pyrex installed,
-and that your source releases will be similarly usable with or without Pyrex.
+source files. This will ensure that people tracking your project in a revision
+control system will be able to build it even if they don't have Pyrex
+installed, and that your source releases will be similarly usable with or
+without Pyrex.
-----------------
@@ -2569,15 +2543,15 @@ the ``cmd`` object's ``write_file()``, ``delete_file()``, and
those methods' docstrings for more details.
-Adding Support for Other Revision Control Systems
+Adding Support for Revision Control Systems
-------------------------------------------------
If you would like to create a plugin for ``setuptools`` to find files in
-source control systems, you can do so by adding an
-entry point to the ``setuptools.file_finders`` group. The entry point should
-be a function accepting a single directory name, and should yield
-all the filenames within that directory (and any subdirectories thereof) that
-are under revision control.
+source control systems, you can do so by adding an entry point to the
+``setuptools.file_finders`` group. The entry point should be a function
+accepting a single directory name, and should yield all the filenames within
+that directory (and any subdirectories thereof) that are under revision
+control.
For example, if you were going to create a plugin for a revision control system
called "foobar", you would write a function something like this:
From 741f3bbcbbbd73076a44100a0e112f6dd86864b6 Mon Sep 17 00:00:00 2001
From: Alexey Kotlyarov
Date: Sun, 20 Mar 2016 20:27:59 +1100
Subject: [PATCH 2/2] Point towards SCM plugins for including source files
---
docs/setuptools.txt | 28 +++++++++++++++++++++-------
1 file changed, 21 insertions(+), 7 deletions(-)
diff --git a/docs/setuptools.txt b/docs/setuptools.txt
index d267bf2914..886216ea37 100644
--- a/docs/setuptools.txt
+++ b/docs/setuptools.txt
@@ -1461,10 +1461,18 @@ use the appropriate defaults.)
Generating Source Distributions
-------------------------------
-If you need to include automatically generated files, 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.
+``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
+`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
@@ -2546,9 +2554,15 @@ those methods' docstrings for more details.
Adding Support for Revision Control Systems
-------------------------------------------------
-If you would like to create a plugin for ``setuptools`` to find files in
-source control systems, you can do so by adding an entry point to the
-``setuptools.file_finders`` group. The entry point should be a function
+If the files you want to include in the source distribution are tracked using
+Git, Mercurial or SVN, you can use the following packages to achieve that:
+
+- Git and Mercurial: `setuptools_scm `_
+- SVN: `setuptools_svn `_
+
+If you would like to create a plugin for ``setuptools`` to find files tracked
+by another revision control system, you can do so by adding an entry point to
+the ``setuptools.file_finders`` group. The entry point should be a function
accepting a single directory name, and should yield all the filenames within
that directory (and any subdirectories thereof) that are under revision
control.