Merge pull request #8589 from shireenrao/upd-pip-docs

pypa · Sep 24, 2020 · 75befb5 · 75befb5
2 parents 864b5e7 + 8f31513
commit 75befb5
Show file tree

Hide file tree

Showing 22 changed files with 1,799 additions and 450 deletions.
diff --git a/docs/html/conf.py b/docs/html/conf.py
@@ -30,7 +30,12 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 # extensions = ['sphinx.ext.autodoc']
-extensions = ['sphinx.ext.extlinks', 'pip_sphinxext', 'sphinx.ext.intersphinx']
+extensions = [
+    'sphinx.ext.extlinks',
+    'pip_sphinxext',
+    'sphinx.ext.intersphinx',
+    'sphinx_tabs.tabs',
+]
 
 # intersphinx
 intersphinx_cache_limit = 0
@@ -130,6 +135,9 @@
     'pypi': ('https://pypi.org/project/%s/', ''),
 }
 
+# Turn off sphinx build warnings because of sphinx tabs during man pages build
+sphinx_tabs_nowarn = True
+
 # -- Options for HTML output --------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with

diff --git a/docs/html/development/getting-started.rst b/docs/html/development/getting-started.rst
@@ -38,13 +38,25 @@ To run the pip executable from your source tree during development, install pip
 locally using editable installation (inside a virtualenv).
 You can then invoke your local source tree pip normally.
 
-.. code-block:: console
+.. tabs::
+
+   .. group-tab:: Unix/macOS
+
+      .. code-block:: shell
+
+         virtualenv venv # You can also use "python -m venv venv" from python3.3+
+         source venv/bin/activate
+         python -m pip install -e .
+         python -m pip --version
+
+   .. group-tab:: Windows
 
-    $ virtualenv venv # You can also use "python -m venv venv" from python3.3+
-    $ source venv/bin/activate
-    $ python -m pip install -e .
-    $ python -m pip --version
+      .. code-block:: shell
 
+         virtualenv venv # You can also use "py -m venv venv" from python3.3+
+         venv\Scripts\activate
+         py -m pip install -e .
+         py -m pip --version
 
 Running Tests
 =============

diff --git a/docs/html/installing.rst b/docs/html/installing.rst
@@ -26,9 +26,21 @@ this link: `get-pip.py
  curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
 
 Then run the following command in the folder where you
-have downloaded ``get-pip.py``::
+have downloaded ``get-pip.py``:
 
- python get-pip.py
+.. tabs::
+
+   .. group-tab:: Unix/macOS
+
+      .. code-block:: shell
+
+         python get-pip.py
+
+   .. group-tab:: Windows
+
+      .. code-block:: shell
+
+         py get-pip.py
 
 
 .. warning::
@@ -67,23 +79,70 @@ get-pip.py options
 install Options>` and the :ref:`general options <General Options>`. Below are
 some examples:
 
-Install from local copies of pip and setuptools::
+Install from local copies of pip and setuptools:
+
+.. tabs::
+
+   .. group-tab:: Unix/macOS
+
+      .. code-block:: shell
+
+         python get-pip.py --no-index --find-links=/local/copies
+
+   .. group-tab:: Windows
+
+      .. code-block:: shell
+
+         py get-pip.py --no-index --find-links=/local/copies
+
+Install to the user site [3]_:
+
+.. tabs::
+
+   .. group-tab:: Unix/macOS
 
-  python get-pip.py --no-index --find-links=/local/copies
+      .. code-block:: shell
 
-Install to the user site [3]_::
+         python get-pip.py --user
 
-  python get-pip.py --user
+   .. group-tab:: Windows
 
-Install behind a proxy::
+      .. code-block:: shell
 
-  python get-pip.py --proxy="http://[user:passwd@]proxy.server:port"
+         py get-pip.py --user
+
+Install behind a proxy:
+
+.. tabs::
+
+   .. group-tab:: Unix/macOS
+
+      .. code-block:: shell
+
+         python get-pip.py --proxy="http://[user:passwd@]proxy.server:port"
+
+   .. group-tab:: Windows
+
+      .. code-block:: shell
+
+         py 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
+.. tabs::
 
+   .. group-tab:: Unix/macOS
+
+      .. code-block:: shell
+
+         python get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0
+
+   .. group-tab:: Windows
+
+      .. code-block:: shell
+
+         py get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0
 
 Using Linux Package Managers
 ============================
@@ -97,14 +156,19 @@ the `Python Packaging User Guide
 Upgrading pip
 =============
 
-On Linux or macOS::
+.. tabs::
+
+   .. group-tab:: Unix/macOS
 
- pip install -U pip
+      .. code-block:: shell
 
+         python -m pip install -U pip
 
-On Windows [4]_::
+   .. group-tab:: Windows
 
- python -m pip install -U pip
+      .. code-block:: shell
+
+         py -m pip install -U pip
 
 
 .. _compatibility-requirements:
@@ -134,5 +198,3 @@ pip works on Unix/Linux, macOS, and Windows.
        ``--user`` installs for pip itself, should not be considered to be fully
        tested or endorsed. For discussion, see `Issue 1668
        <https://github.com/pypa/pip/issues/1668>`_.
-
-.. [4] https://github.com/pypa/pip/issues/1299
diff --git a/docs/html/quickstart.rst b/docs/html/quickstart.rst
@@ -6,62 +6,145 @@ First, :doc:`install pip <installing>`.
 
 Install a package from `PyPI`_:
 
-::
+.. tabs::
+
+   .. group-tab:: Unix/macOS
+
+      .. code-block:: console
+
+         $ python -m pip install SomePackage
+         [...]
+         Successfully installed SomePackage
+
+   .. group-tab:: Windows
+
+      .. code-block:: console
+
+         C:\> py -m pip install SomePackage
+         [...]
+         Successfully installed SomePackage
 
-  $ pip install SomePackage
-  [...]
-  Successfully installed SomePackage
 
 Install a package that's already been downloaded from `PyPI`_ or
 obtained from elsewhere. This is useful if the target machine does not have a
 network connection:
 
-::
+.. tabs::
+
+   .. group-tab:: Unix/macOS
+
+      .. code-block:: console
+
+         $ python -m pip install SomePackage-1.0-py2.py3-none-any.whl
+         [...]
+         Successfully installed SomePackage
+
+   .. group-tab:: Windows
+
+      .. code-block:: console
+
+         C:\> py -m pip install SomePackage-1.0-py2.py3-none-any.whl
+         [...]
+         Successfully installed SomePackage
 
-  $ pip install SomePackage-1.0-py2.py3-none-any.whl
-  [...]
-  Successfully installed SomePackage
 
 Show what files were installed:
 
-::
+.. tabs::
+
+   .. group-tab:: Unix/macOS
+
+      .. code-block:: console
+
+         $ python -m pip show --files SomePackage
+         Name: SomePackage
+         Version: 1.0
+         Location: /my/env/lib/pythonx.x/site-packages
+         Files:
+         ../somepackage/__init__.py
+         [...]
+
+   .. group-tab:: Windows
 
-  $ pip show --files SomePackage
-  Name: SomePackage
-  Version: 1.0
-  Location: /my/env/lib/pythonx.x/site-packages
-  Files:
-    ../somepackage/__init__.py
-    [...]
+      .. code-block:: console
+
+         C:\> py -m pip show --files SomePackage
+         Name: SomePackage
+         Version: 1.0
+         Location: /my/env/lib/pythonx.x/site-packages
+         Files:
+         ../somepackage/__init__.py
+         [...]
 
 List what packages are outdated:
 
-::
+.. tabs::
+
+   .. group-tab:: Unix/macOS
+
+      .. code-block:: console
+
+         $ python -m pip list --outdated
+         SomePackage (Current: 1.0 Latest: 2.0)
 
-  $ pip list --outdated
-  SomePackage (Current: 1.0 Latest: 2.0)
+   .. group-tab:: Windows
+
+      .. code-block:: console
+
+         C:\> py -m pip list --outdated
+         SomePackage (Current: 1.0 Latest: 2.0)
 
 Upgrade a package:
 
-::
+.. tabs::
+
+   .. group-tab:: Unix/macOS
+
+      .. code-block:: console
 
-  $ pip install --upgrade SomePackage
-  [...]
-  Found existing installation: SomePackage 1.0
-  Uninstalling SomePackage:
-    Successfully uninstalled SomePackage
-  Running setup.py install for SomePackage
-  Successfully installed SomePackage
+         $ python -m pip install --upgrade SomePackage
+         [...]
+         Found existing installation: SomePackage 1.0
+         Uninstalling SomePackage:
+         Successfully uninstalled SomePackage
+         Running setup.py install for SomePackage
+         Successfully installed SomePackage
+
+   .. group-tab:: Windows
+
+      .. code-block:: console
+
+         C:\> py -m pip install --upgrade SomePackage
+         [...]
+         Found existing installation: SomePackage 1.0
+         Uninstalling SomePackage:
+         Successfully uninstalled SomePackage
+         Running setup.py install for SomePackage
+         Successfully installed SomePackage
 
 Uninstall a package:
 
-::
+.. tabs::
+
+   .. group-tab:: Unix/macOS
+
+      .. code-block:: console
+
+         $ python -m pip uninstall SomePackage
+         Uninstalling SomePackage:
+         /my/env/lib/pythonx.x/site-packages/somepackage
+         Proceed (y/n)? y
+         Successfully uninstalled SomePackage
+
+   .. group-tab:: Windows
+
+      .. code-block:: console
 
-  $ pip uninstall SomePackage
-  Uninstalling SomePackage:
-    /my/env/lib/pythonx.x/site-packages/somepackage
-  Proceed (y/n)? y
-  Successfully uninstalled SomePackage
+         C:\> py -m pip uninstall SomePackage
+         Uninstalling SomePackage:
+           /my/env/lib/pythonx.x/site-packages/somepackage
+         Proceed (y/n)? y
+         Successfully uninstalled SomePackage
 
 
 .. _PyPI: https://pypi.org/