From a163ae5af17f4ada486e70f759821dcb01d86b1f Mon Sep 17 00:00:00 2001 From: Chris Jerdonek Date: Tue, 7 May 2019 09:13:56 -0400 Subject: [PATCH] Fix some formatting issues in the pip-install docs (#6432) --- docs/html/installing.rst | 2 +- docs/html/reference/pip_install.rst | 51 +++++++++++++++------------ src/pip/_internal/cli/cmdoptions.py | 2 +- src/pip/_internal/commands/install.py | 2 +- 4 files changed, 31 insertions(+), 26 deletions(-) diff --git a/docs/html/installing.rst b/docs/html/installing.rst index 35ba05db9..73f6f90b8 100644 --- a/docs/html/installing.rst +++ b/docs/html/installing.rst @@ -77,7 +77,7 @@ Install behind a proxy:: python get-pip.py --proxy="http://[user:passwd@]proxy.server:port" ``get-pip.py`` can also be used to install a specified combination of ``pip``, -``setuptools``, and ``wheel`` using the same requirements syntax as ``pip``:: +``setuptools``, and ``wheel`` using the same requirements syntax as pip:: python get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0 diff --git a/docs/html/reference/pip_install.rst b/docs/html/reference/pip_install.rst index a45a67576..b3afc68e4 100644 --- a/docs/html/reference/pip_install.rst +++ b/docs/html/reference/pip_install.rst @@ -72,7 +72,7 @@ Installation Order ++++++++++++++++++ As of v6.1.0, pip installs dependencies before their dependents, i.e. in -"topological order". This is the only commitment pip currently makes related +"topological order." This is the only commitment pip currently makes related to order. While it may be coincidentally true that pip will install things in the order of the install arguments or in the order of the items in a requirements file, this is not a promise. @@ -154,7 +154,8 @@ The following options are supported: * :ref:`--only-binary ` * :ref:`--require-hashes <--require-hashes>` -For example, to specify :ref:`--no-index <--no-index>` and 2 :ref:`--find-links <--find-links>` locations: +For example, to specify :ref:`--no-index <--no-index>` and two +:ref:`--find-links <--find-links>` locations: :: @@ -238,7 +239,7 @@ pip supports installing from a package index using a :term:`requirement specifier `. Generally speaking, a requirement specifier is composed of a project name followed by optional :term:`version specifiers `. :pep:`508` contains a full specification -of the format of a requirement (``pip`` does not support the ``url_req`` form +of the format of a requirement (pip does not support the ``url_req`` form of specifier at this time). Some examples: @@ -331,32 +332,35 @@ VCS Support +++++++++++ pip supports installing from Git, Mercurial, Subversion and Bazaar, and detects -the type of VCS using url prefixes: "git+", "hg+", "bzr+", "svn+". +the type of VCS using url prefixes: ``git+``, ``hg+``, ``svn+``, and ``bzr+``. -pip requires a working VCS command on your path: git, hg, svn, or bzr. +pip requires a working VCS command on your path: ``git``, ``hg``, ``svn``, or +``bzr``. VCS projects can be installed in :ref:`editable mode ` (using the :ref:`--editable ` option) or not. -* For editable installs, the clone location by default is "/src/SomeProject" in virtual environments, and "/src/SomeProject" +* For editable installs, the clone location by default is ``/src/SomeProject`` in virtual environments, and + ``/src/SomeProject`` for global installs. The :ref:`--src ` option can be used to modify this location. * For non-editable installs, the project is built locally in a temp dir and then installed normally. Note that if a satisfactory version of the package is - already installed, the VCS source will not overwrite it without an `--upgrade` - flag. VCS requirements pin the package version (specified in the `setup.py` - file) of the target commit, not necessarily the commit itself. + already installed, the VCS source will not overwrite it without an + ``--upgrade`` flag. VCS requirements pin the package version (specified + in the ``setup.py`` file) of the target commit, not necessarily the commit + itself. * The :ref:`pip freeze` subcommand will record the VCS requirement specifier (referencing a specific commit) if and only if the install is done using the editable option. -The "project name" component of the url suffix "egg=" +The "project name" component of the url suffix ``egg=`` is used by pip in its dependency logic to identify the project prior to pip downloading and analyzing the metadata. For projects -where setup.py is not in the root of project, "subdirectory" component -is used. Value of "subdirectory" component should be a path starting from root -of the project to where setup.py is located. +where ``setup.py`` is not in the root of project, the "subdirectory" component +is used. The value of the "subdirectory" component should be a path starting +from the root of the project to where ``setup.py`` is located. So if your repository layout is: @@ -482,12 +486,13 @@ pip searches for packages on `PyPI`_ using the which is documented `here `_ and `there `_ -pip offers a number of Package Index Options for modifying how packages are found. +pip offers a number of package index options for modifying how packages are +found. -pip looks for packages in a number of places, on PyPI (if not disabled via -```--no-index```), in the local filesystem, and in any additional repositories -specified via ```--find-links``` or ```--index-url```. There is no ordering in -the locations that are searched, rather they are all checked, and the "best" +pip looks for packages in a number of places: on PyPI (if not disabled via +``--no-index``), in the local filesystem, and in any additional repositories +specified via ``--find-links`` or ``--index-url``. There is no ordering in +the locations that are searched. Rather they are all checked, and the "best" match for the requirements (in terms of version number - see :pep:`440` for details) is selected. @@ -711,12 +716,12 @@ Controlling setup_requires Setuptools offers the ``setup_requires`` `setup() keyword `_ -for specifying dependencies that need to be present in order for the `setup.py` -script to run. Internally, Setuptools uses ``easy_install`` to fulfill these -dependencies. +for specifying dependencies that need to be present in order for the +``setup.py`` script to run. Internally, Setuptools uses ``easy_install`` +to fulfill these dependencies. pip has no way to control how these dependencies are located. None of the -Package Index Options have an effect. +package index options have an effect. The solution is to configure a "system" or "personal" `Distutils configuration file diff --git a/src/pip/_internal/cli/cmdoptions.py b/src/pip/_internal/cli/cmdoptions.py index a09e38f70..bde97ab25 100644 --- a/src/pip/_internal/cli/cmdoptions.py +++ b/src/pip/_internal/cli/cmdoptions.py @@ -305,7 +305,7 @@ index_url = partial( dest='index_url', metavar='URL', default=PyPI.simple_url, - help="Base URL of Python Package Index (default %default). " + help="Base URL of the Python Package Index (default %default). " "This should point to a repository compliant with PEP 503 " "(the simple repository API) or a local directory laid out " "in the same format.", diff --git a/src/pip/_internal/commands/install.py b/src/pip/_internal/commands/install.py index c13da44c6..788268ef5 100644 --- a/src/pip/_internal/commands/install.py +++ b/src/pip/_internal/commands/install.py @@ -79,7 +79,7 @@ class InstallCommand(RequirementCommand): - Local project directories. - Local or remote source archives. - pip also supports installing from "requirements files", which provide + pip also supports installing from "requirements files," which provide an easy way to specify a whole environment to be installed. """ name = 'install'