diff options
| -rw-r--r-- | Doc/distutils/_setuptools_disclaimer.rst | 5 | ||||
| -rw-r--r-- | Doc/distutils/apiref.rst | 10 | ||||
| -rw-r--r-- | Doc/distutils/builtdist.rst | 2 | ||||
| -rw-r--r-- | Doc/distutils/commandref.rst | 2 | ||||
| -rw-r--r-- | Doc/distutils/configfile.rst | 2 | ||||
| -rw-r--r-- | Doc/distutils/examples.rst | 2 | ||||
| -rw-r--r-- | Doc/distutils/extending.rst | 2 | ||||
| -rw-r--r-- | Doc/distutils/index.rst | 10 | ||||
| -rw-r--r-- | Doc/distutils/introduction.rst | 2 | ||||
| -rw-r--r-- | Doc/distutils/setupscript.rst | 2 | ||||
| -rw-r--r-- | Doc/distutils/sourcedist.rst | 2 | ||||
| -rw-r--r-- | Doc/install/index.rst | 84 | ||||
| -rw-r--r-- | Doc/tools/susp-ignored.csv | 2 | ||||
| -rw-r--r-- | Misc/NEWS.d/next/Documentation/2019-05-05-07-58-50.bpo-36797.W1X4On.rst | 3 |
14 files changed, 60 insertions, 70 deletions
diff --git a/Doc/distutils/_setuptools_disclaimer.rst b/Doc/distutils/_setuptools_disclaimer.rst new file mode 100644 index 0000000..cc75858 --- /dev/null +++ b/Doc/distutils/_setuptools_disclaimer.rst @@ -0,0 +1,5 @@ +.. note:: + + This document is being retained solely until the ``setuptools`` documentation + at https://setuptools.readthedocs.io/en/latest/setuptools.html + independently covers all of the relevant information currently included here. diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst index 1facc04..cbeedab 100644 --- a/Doc/distutils/apiref.rst +++ b/Doc/distutils/apiref.rst @@ -4,6 +4,16 @@ API Reference ************* +.. seealso:: + + `New and changed setup.py arguments in setuptools <setuptools-setup-py>`_ + The ``setuptools`` project adds new capabilities to the ``setup`` function + and other APIs, makes the API consistent across different Python versions, + and is hence recommended over using ``distutils`` directly. + +.. _setuptools-setup-py: https://setuptools.readthedocs.io/en/latest/setuptools.html#new-and-changed-setup-keywords + +.. include:: ./_setuptools_disclaimer.rst :mod:`distutils.core` --- Core Distutils functionality ====================================================== diff --git a/Doc/distutils/builtdist.rst b/Doc/distutils/builtdist.rst index f1f3471..f44d0d0 100644 --- a/Doc/distutils/builtdist.rst +++ b/Doc/distutils/builtdist.rst @@ -4,6 +4,8 @@ Creating Built Distributions **************************** +.. include:: ./_setuptools_disclaimer.rst + A "built distribution" is what you're probably used to thinking of either as a "binary package" or an "installer" (depending on your background). It's not necessarily binary, though, because it might contain only Python source code diff --git a/Doc/distutils/commandref.rst b/Doc/distutils/commandref.rst index 6a2ac96..0f6fe2a 100644 --- a/Doc/distutils/commandref.rst +++ b/Doc/distutils/commandref.rst @@ -4,6 +4,8 @@ Command Reference ***************** +.. include:: ./_setuptools_disclaimer.rst + .. % \section{Building modules: the \protect\command{build} command family} .. % \label{build-cmds} .. % \subsubsection{\protect\command{build}} diff --git a/Doc/distutils/configfile.rst b/Doc/distutils/configfile.rst index 0874d05..2a5c832 100644 --- a/Doc/distutils/configfile.rst +++ b/Doc/distutils/configfile.rst @@ -4,6 +4,8 @@ Writing the Setup Configuration File ************************************ +.. include:: ./_setuptools_disclaimer.rst + Often, it's not possible to write down everything needed to build a distribution *a priori*: you may need to get some information from the user, or from the user's system, in order to proceed. As long as that information is fairly diff --git a/Doc/distutils/examples.rst b/Doc/distutils/examples.rst index f81e06b..4ac552c 100644 --- a/Doc/distutils/examples.rst +++ b/Doc/distutils/examples.rst @@ -4,6 +4,8 @@ Examples ******** +.. include:: ./_setuptools_disclaimer.rst + This chapter provides a number of basic examples to help get started with distutils. Additional information about using distutils can be found in the Distutils Cookbook. diff --git a/Doc/distutils/extending.rst b/Doc/distutils/extending.rst index 501fd7c..1075e81 100644 --- a/Doc/distutils/extending.rst +++ b/Doc/distutils/extending.rst @@ -4,6 +4,8 @@ Extending Distutils ******************* +.. include:: ./_setuptools_disclaimer.rst + Distutils can be extended in various ways. Most extensions take the form of new commands or replacements for existing commands. New commands may be written to support new types of platform-specific packaging, for example, while diff --git a/Doc/distutils/index.rst b/Doc/distutils/index.rst index d6f7640..c56fafd 100644 --- a/Doc/distutils/index.rst +++ b/Doc/distutils/index.rst @@ -12,10 +12,7 @@ :ref:`distributing-index` The up to date module distribution documentations -This document describes the Python Distribution Utilities ("Distutils") from -the module developer's point of view, describing how to use the Distutils to -make Python modules and extensions easily available to a wider audience with -very little overhead for build/release/install mechanics. +.. include:: ./_setuptools_disclaimer.rst .. note:: @@ -25,6 +22,11 @@ very little overhead for build/release/install mechanics. recommendations section <https://packaging.python.org/guides/tool-recommendations/>`__ in the Python Packaging User Guide for more information. +This document describes the Python Distribution Utilities ("Distutils") from +the module developer's point of view, describing the underlying capabilities +that ``setuptools`` builds on to allow Python developers to make Python modules +and extensions readily available to a wider audience. + .. toctree:: :maxdepth: 2 :numbered: diff --git a/Doc/distutils/introduction.rst b/Doc/distutils/introduction.rst index 7721484..1f8a560 100644 --- a/Doc/distutils/introduction.rst +++ b/Doc/distutils/introduction.rst @@ -4,6 +4,8 @@ An Introduction to Distutils **************************** +.. include:: ./_setuptools_disclaimer.rst + This document covers using the Distutils to distribute your Python modules, concentrating on the role of developer/distributor: if you're looking for information on installing Python modules, you should refer to the diff --git a/Doc/distutils/setupscript.rst b/Doc/distutils/setupscript.rst index 1f99f62..4386a60 100644 --- a/Doc/distutils/setupscript.rst +++ b/Doc/distutils/setupscript.rst @@ -4,6 +4,8 @@ Writing the Setup Script ************************ +.. include:: ./_setuptools_disclaimer.rst + The setup script is the centre of all activity in building, distributing, and installing modules using the Distutils. The main purpose of the setup script is to describe your module distribution to the Distutils, so that the various diff --git a/Doc/distutils/sourcedist.rst b/Doc/distutils/sourcedist.rst index 0ac8ef4..0600663 100644 --- a/Doc/distutils/sourcedist.rst +++ b/Doc/distutils/sourcedist.rst @@ -4,6 +4,8 @@ Creating a Source Distribution ****************************** +.. include:: ./_setuptools_disclaimer.rst + As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command to create a source distribution. In the simplest case, :: diff --git a/Doc/install/index.rst b/Doc/install/index.rst index f6a8cd6..e142324 100644 --- a/Doc/install/index.rst +++ b/Doc/install/index.rst @@ -13,23 +13,10 @@ .. seealso:: :ref:`installing-index` - The up to date module installation documentations - -.. The audience for this document includes people who don't know anything - about Python and aren't about to learn the language just in order to - install and maintain it for their users, i.e. system administrators. - Thus, I have to be sure to explain the basics at some point: - sys.path and PYTHONPATH at least. Should probably give pointers to - other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc. - - Finally, it might be useful to include all the material from my "Care - and Feeding of a Python Installation" talk in here somewhere. Yow! - -This document describes the Python Distribution Utilities ("Distutils") from the -end-user's point-of-view, describing how to extend the capabilities of a -standard Python installation by building and installing third-party Python -modules and extensions. + The up to date module installation documentation. For regular Python + usage, you almost certainly want that document rather than this one. +.. include:: ../distutils/_setuptools_disclaimer.rst .. note:: @@ -46,59 +33,26 @@ modules and extensions. Introduction ============ -Although Python's extensive standard library covers many programming needs, -there often comes a time when you need to add some new functionality to your -Python installation in the form of third-party modules. This might be necessary -to support your own programming, or to support an application that you want to -use and that happens to be written in Python. - -In the past, there has been little support for adding third-party modules to an -existing Python installation. With the introduction of the Python Distribution -Utilities (Distutils for short) in Python 2.0, this changed. - -This document is aimed primarily at the people who need to install third-party -Python modules: end-users and system administrators who just need to get some -Python application running, and existing Python programmers who want to add some -new goodies to their toolbox. You don't need to know Python to read this -document; there will be some brief forays into using Python's interactive mode -to explore your installation, but that's it. If you're looking for information -on how to distribute your own Python modules so that others may use them, see -the :ref:`distutils-index` manual. :ref:`debug-setup-script` may also be of -interest. - - -.. _inst-trivial-install: - -Best case: trivial installation -------------------------------- - -In the best case, someone will have prepared a special version of the module -distribution you want to install that is targeted specifically at your platform -and is installed just like any other software on your platform. For example, -the module developer might make an executable installer available for Windows -users, an RPM package for users of RPM-based Linux systems (Red Hat, SuSE, -Mandrake, and many others), a Debian package for users of Debian-based Linux -systems, and so forth. - -In that case, you would download the installer appropriate to your platform and -do the obvious thing with it: run it if it's an executable installer, ``rpm ---install`` it if it's an RPM, etc. You don't need to run Python or a setup -script, you don't need to compile anything---you might not even need to read any -instructions (although it's always a good idea to do so anyway). - -Of course, things will not always be that easy. You might be interested in a -module distribution that doesn't have an easy-to-use installer for your -platform. In that case, you'll have to start with the source distribution -released by the module's author/maintainer. Installing from a source -distribution is not too hard, as long as the modules are packaged in the -standard way. The bulk of this document is about building and installing -modules from standard source distributions. +In Python 2.0, the ``distutils`` API was first added to the standard library. +This provided Linux distro maintainers with a standard way of converting +Python projects into Linux distro packages, and system administrators with a +standard way of installing them directly onto target systems. + +In the many years since Python 2.0 was released, tightly coupling the build +system and package installer to the language runtime release cycle has turned +out to be problematic, and it is now recommended that projects use the +``pip`` package installer and the ``setuptools`` build system, rather than +using ``distutils`` directly. + +See :ref:`installing-index` and :ref:`distributing-index` for more details. +This legacy documentation is being retained only until we're confident that the +``setuptools`` documentation covers everything needed. .. _inst-new-standard: -The new standard: Distutils ---------------------------- +Distutils based source distributions +------------------------------------ If you download a module source distribution, you can tell pretty quickly if it was packaged and distributed in the standard way, i.e. using the Distutils. diff --git a/Doc/tools/susp-ignored.csv b/Doc/tools/susp-ignored.csv index 3672955..31b2266 100644 --- a/Doc/tools/susp-ignored.csv +++ b/Doc/tools/susp-ignored.csv @@ -4,7 +4,7 @@ c-api/sequence,,:i2,del o[i1:i2] c-api/sequence,,:i2,o[i1:i2] c-api/unicode,,:end,str[start:end] c-api/unicode,,:start,unicode[start:start+length] -distutils/examples,267,`,This is the description of the ``foobar`` package. +distutils/examples,274,`,This is the description of the ``foobar`` package. distutils/setupscript,,::, extending/embedding,,:numargs,"if(!PyArg_ParseTuple(args, "":numargs""))" extending/extending,,:myfunction,"PyArg_ParseTuple(args, ""D:myfunction"", &c);" diff --git a/Misc/NEWS.d/next/Documentation/2019-05-05-07-58-50.bpo-36797.W1X4On.rst b/Misc/NEWS.d/next/Documentation/2019-05-05-07-58-50.bpo-36797.W1X4On.rst new file mode 100644 index 0000000..5ca5555 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2019-05-05-07-58-50.bpo-36797.W1X4On.rst @@ -0,0 +1,3 @@ +More of the legacy distutils documentation has been either pruned, or else +more clearly marked as being retained solely until the setuptools +documentation covers it independently. |