bpo-25592: Improve documentation of distutils data_files (GH-9767) (G… · python/cpython@ebae1ce
@@ -524,20 +524,23 @@ following way::
524524 setup(...,
525525 data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
526526 ('config', ['cfg/data.cfg']),
527- ('/etc/init.d', ['init-script'])]
528527 )
529528530-Note that you can specify the directory names where the data files will be
531-installed, but you cannot rename the data files themselves.
532-533529Each (*directory*, *files*) pair in the sequence specifies the installation
534-directory and the files to install there. If *directory* is a relative path, it
535-is interpreted relative to the installation prefix (Python's ``sys.prefix`` for
536-pure-Python packages, ``sys.exec_prefix`` for packages that contain extension
537-modules). Each file name in *files* is interpreted relative to the
538-:file:`setup.py` script at the top of the package source distribution. No
539-directory information from *files* is used to determine the final location of
540-the installed file; only the name of the file is used.
530+directory and the files to install there.
531+532+Each file name in *files* is interpreted relative to the :file:`setup.py`
533+script at the top of the package source distribution. Note that you can
534+specify the directory where the data files will be installed, but you cannot
535+rename the data files themselves.
536+537+The *directory* should be a relative path. It is interpreted relative to the
538+installation prefix (Python's ``sys.prefix`` for system installations;
539+``site.USER_BASE`` for user installations). Distutils allows *directory* to be
540+an absolute installation path, but this is discouraged since it is
541+incompatible with the wheel packaging format. No directory information from
542+*files* is used to determine the final location of the installed file; only
543+the name of the file is used.
541544542545You can specify the ``data_files`` options as a simple sequence of files
543546without specifying a target directory, but this is not recommended, and the