Replace 'pip search' docs with 'pip index versions'

Author: hugovk

docs/html/cli/index.md

@@ -31,6 +31,13 @@ pip_wheel
 pip_hash
 ```
 
+```{toctree}
+:maxdepth: 1
+:caption: Package Index information
+
+pip_index
+```
+
 ```{toctree}
 :maxdepth: 1
 :caption: Managing pip itself

docs/html/cli/pip_index.rst

@@ -0,0 +1,52 @@
+.. _`pip index`:
+
+=========
+pip index
+=========
+
+Usage
+=====
+
+.. tab:: Unix/macOS
+
+   .. pip-command-usage:: index "python -m pip"
+
+.. tab:: Windows
+
+   .. pip-command-usage:: index "py -m pip"
+
+
+Description
+===========
+
+.. pip-command-description:: index
+
+
+Options
+=======
+
+.. pip-command-options:: index
+
+
+Examples
+========
+
+#. Search for "peppercorn"
+
+   .. tab:: Unix/macOS
+
+      .. code-block:: console
+
+         $ python -m pip index versions peppercorn
+          WARNING: pip index is currently an experimental command. It may be removed/changed in a future release without prior warning.
+          peppercorn (0.6)
+          Available versions: 0.6, 0.5, 0.4, 0.3, 0.2, 0.1
+
+   .. tab:: Windows
+
+      .. code-block:: console
+
+         C:\> py -m pip index versions peppercorn
+         WARNING: pip index is currently an experimental command. It may be removed/changed in a future release without prior warning.
+         peppercorn (0.6)
+         Available versions: 0.6, 0.5, 0.4, 0.3, 0.2, 0.1

docs/html/user_guide.rst

@@ -428,6 +428,28 @@ For more information and examples, see the :ref:`pip list` and :ref:`pip show`
 reference pages.
 
 
+Searching for Packages
+======================
+
+pip can search `PyPI`_ for packages using the ``pip index versions``
+subcommand:
+
+.. tab:: Unix/macOS
+
+   .. code-block:: shell
+
+      python -m pip index versions "package"
+
+.. tab:: Windows
+
+   .. code-block:: shell
+
+      py -m pip index versions "package"
+
+This lists all available versions of a given package.
+
+For more information and examples, see the :ref:`pip index` reference.
+
 .. _`Configuration`:
 
 

docs/man/commands/index.rst

@@ -0,0 +1,20 @@
+:orphan:
+
+==========
+pip-index
+==========
+
+Description
+***********
+
+.. pip-command-description:: indx
+
+Usage
+*****
+
+.. pip-command-usage:: index
+
+Options
+*******
+
+.. pip-command-options:: index

news/5216.removal.rst

@@ -1 +1,2 @@
-Remove the ``pip search`` command as it is basically a no-op with PyPI.
+Remove the ``pip search`` command because it no longer works. The command was never
+standardised and common uses can be replaced with ``pip index``.