[Python-checkins] bpo-25592: Improve documentation of distutils data_files (GH-9767) (GH-11701)

[Antoine Pitrou]

https://github.com/python/cpython/commit/ebae1ce9c40e62ce52dc968f86ed11578d2fcdfd
commit: ebae1ce9c40e62ce52dc968f86ed11578d2fcdfd
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: Antoine Pitrou <pitrou at free.fr>
date: 2019-01-30T16:56:51+01:00
summary:

bpo-25592: Improve documentation of distutils data_files (GH-9767) (GH-11701)

(cherry picked from commit 598e15d4feaee3849a91d92c9ca51f17baafe19c)

Co-authored-by: jdemeyer <J.Demeyer at UGent.be>

files:
M Doc/distutils/setupscript.rst

diff --git a/Doc/distutils/setupscript.rst b/Doc/distutils/setupscript.rst
index c1051d2e807e..54ed1aebc242 100644
--- a/Doc/distutils/setupscript.rst
+++ b/Doc/distutils/setupscript.rst
@@ -524,20 +524,23 @@ following way::
     setup(...,
           data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
                       ('config', ['cfg/data.cfg']),
-                      ('/etc/init.d', ['init-script'])]
          )
 
-Note that you can specify the directory names where the data files will be
-installed, but you cannot rename the data files themselves.
-
 Each (*directory*, *files*) pair in the sequence specifies the installation
-directory and the files to install there.  If *directory* is a relative path, it
-is interpreted relative to the installation prefix (Python's ``sys.prefix`` for
-pure-Python packages, ``sys.exec_prefix`` for packages that contain extension
-modules).  Each file name in *files* is interpreted relative to the
-:file:`setup.py` script at the top of the package source distribution.  No
-directory information from *files* is used to determine the final location of
-the installed file; only the name of the file is used.
+directory and the files to install there.
+
+Each file name in *files* is interpreted relative to the :file:`setup.py`
+script at the top of the package source distribution. Note that you can
+specify the directory where the data files will be installed, but you cannot
+rename the data files themselves.
+
+The *directory* should be a relative path. It is interpreted relative to the
+installation prefix (Python's ``sys.prefix`` for system installations;
+``site.USER_BASE`` for user installations). Distutils allows *directory* to be
+an absolute installation path, but this is discouraged since it is
+incompatible with the wheel packaging format. No directory information from
+*files* is used to determine the final location of the installed file; only
+the name of the file is used.
 
 You can specify the ``data_files`` options as a simple sequence of files
 without specifying a target directory, but this is not recommended, and the