Skip to content

Commit 75befb5

Browse files
pradyunsgpradyunsg
authored
Merge pull request #8589 from shireenrao/upd-pip-docs
2 parents 864b5e7 + 8f31513 commit 75befb5

22 files changed

+1799
-450
lines changed

‎docs/html/conf.py

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,12 @@
3030
# Add any Sphinx extension module names here, as strings. They can be
3131
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
3232
# extensions = ['sphinx.ext.autodoc']
33-
extensions = ['sphinx.ext.extlinks', 'pip_sphinxext', 'sphinx.ext.intersphinx']
33+
extensions = [
34+
'sphinx.ext.extlinks',
35+
'pip_sphinxext',
36+
'sphinx.ext.intersphinx',
37+
'sphinx_tabs.tabs',
38+
]
3439

3540
# intersphinx
3641
intersphinx_cache_limit = 0
@@ -130,6 +135,9 @@
130135
'pypi': ('https://pypi.org/project/%s/', ''),
131136
}
132137

138+
# Turn off sphinx build warnings because of sphinx tabs during man pages build
139+
sphinx_tabs_nowarn = True
140+
133141
# -- Options for HTML output --------------------------------------------------
134142

135143
# The theme to use for HTML and HTML Help pages. Major themes that come with

‎docs/html/development/getting-started.rst

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -38,13 +38,25 @@ To run the pip executable from your source tree during development, install pip
3838
locally using editable installation (inside a virtualenv).
3939
You can then invoke your local source tree pip normally.
4040

41-
.. code-block:: console
41+
.. tabs::
42+
43+
.. group-tab:: Unix/macOS
44+
45+
.. code-block:: shell
46+
47+
virtualenv venv # You can also use "python -m venv venv" from python3.3+
48+
source venv/bin/activate
49+
python -m pip install -e .
50+
python -m pip --version
51+
52+
.. group-tab:: Windows
4253

43-
$ virtualenv venv # You can also use "python -m venv venv" from python3.3+
44-
$ source venv/bin/activate
45-
$ python -m pip install -e .
46-
$ python -m pip --version
54+
.. code-block:: shell
4755
56+
virtualenv venv # You can also use "py -m venv venv" from python3.3+
57+
venv\Scripts\activate
58+
py -m pip install -e .
59+
py -m pip --version
4860
4961
Running Tests
5062
=============

‎docs/html/installing.rst

Lines changed: 78 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,21 @@ this link: `get-pip.py
2626
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
2727

2828
Then run the following command in the folder where you
29-
have downloaded ``get-pip.py``::
29+
have downloaded ``get-pip.py``:
3030

31-
python get-pip.py
31+
.. tabs::
32+
33+
.. group-tab:: Unix/macOS
34+
35+
.. code-block:: shell
36+
37+
python get-pip.py
38+
39+
.. group-tab:: Windows
40+
41+
.. code-block:: shell
42+
43+
py get-pip.py
3244
3345
3446
.. warning::
@@ -67,23 +79,70 @@ get-pip.py options
6779
install Options>` and the :ref:`general options <General Options>`. Below are
6880
some examples:
6981

70-
Install from local copies of pip and setuptools::
82+
Install from local copies of pip and setuptools:
83+
84+
.. tabs::
85+
86+
.. group-tab:: Unix/macOS
87+
88+
.. code-block:: shell
89+
90+
python get-pip.py --no-index --find-links=/local/copies
91+
92+
.. group-tab:: Windows
93+
94+
.. code-block:: shell
95+
96+
py get-pip.py --no-index --find-links=/local/copies
97+
98+
Install to the user site [3]_:
99+
100+
.. tabs::
101+
102+
.. group-tab:: Unix/macOS
71103

72-
python get-pip.py --no-index --find-links=/local/copies
104+
.. code-block:: shell
73105
74-
Install to the user site [3]_::
106+
python get-pip.py --user
75107
76-
python get-pip.py --user
108+
.. group-tab:: Windows
77109

78-
Install behind a proxy::
110+
.. code-block:: shell
79111
80-
python get-pip.py --proxy="http://[user:passwd@]proxy.server:port"
112+
py get-pip.py --user
113+
114+
Install behind a proxy:
115+
116+
.. tabs::
117+
118+
.. group-tab:: Unix/macOS
119+
120+
.. code-block:: shell
121+
122+
python get-pip.py --proxy="http://[user:passwd@]proxy.server:port"
123+
124+
.. group-tab:: Windows
125+
126+
.. code-block:: shell
127+
128+
py get-pip.py --proxy="http://[user:passwd@]proxy.server:port"
81129
82130
``get-pip.py`` can also be used to install a specified combination of ``pip``,
83-
``setuptools``, and ``wheel`` using the same requirements syntax as pip::
131+
``setuptools``, and ``wheel`` using the same requirements syntax as pip:
84132

85-
python get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0
133+
.. tabs::
86134

135+
.. group-tab:: Unix/macOS
136+
137+
.. code-block:: shell
138+
139+
python get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0
140+
141+
.. group-tab:: Windows
142+
143+
.. code-block:: shell
144+
145+
py get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0
87146
88147
Using Linux Package Managers
89148
============================
@@ -97,14 +156,19 @@ the `Python Packaging User Guide
97156
Upgrading pip
98157
=============
99158

100-
On Linux or macOS::
159+
.. tabs::
160+
161+
.. group-tab:: Unix/macOS
101162

102-
pip install -U pip
163+
.. code-block:: shell
103164
165+
python -m pip install -U pip
104166
105-
On Windows [4]_::
167+
.. group-tab:: Windows
106168

107-
python -m pip install -U pip
169+
.. code-block:: shell
170+
171+
py -m pip install -U pip
108172
109173
110174
.. _compatibility-requirements:
@@ -134,5 +198,3 @@ pip works on Unix/Linux, macOS, and Windows.
134198
``--user`` installs for pip itself, should not be considered to be fully
135199
tested or endorsed. For discussion, see `Issue 1668
136200
<https://github.com/pypa/pip/issues/1668>`_.
137-
138-
.. [4] https://github.com/pypa/pip/issues/1299

‎docs/html/quickstart.rst

Lines changed: 116 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -6,62 +6,145 @@ First, :doc:`install pip <installing>`.
66

77
Install a package from `PyPI`_:
88

9-
::
9+
.. tabs::
10+
11+
.. group-tab:: Unix/macOS
12+
13+
.. code-block:: console
14+
15+
$ python -m pip install SomePackage
16+
[...]
17+
Successfully installed SomePackage
18+
19+
.. group-tab:: Windows
20+
21+
.. code-block:: console
22+
23+
C:\> py -m pip install SomePackage
24+
[...]
25+
Successfully installed SomePackage
1026
11-
$ pip install SomePackage
12-
[...]
13-
Successfully installed SomePackage
1427
1528
Install a package that's already been downloaded from `PyPI`_ or
1629
obtained from elsewhere. This is useful if the target machine does not have a
1730
network connection:
1831

19-
::
32+
.. tabs::
33+
34+
.. group-tab:: Unix/macOS
35+
36+
.. code-block:: console
37+
38+
$ python -m pip install SomePackage-1.0-py2.py3-none-any.whl
39+
[...]
40+
Successfully installed SomePackage
41+
42+
.. group-tab:: Windows
43+
44+
.. code-block:: console
45+
46+
C:\> py -m pip install SomePackage-1.0-py2.py3-none-any.whl
47+
[...]
48+
Successfully installed SomePackage
2049
21-
$ pip install SomePackage-1.0-py2.py3-none-any.whl
22-
[...]
23-
Successfully installed SomePackage
2450
2551
Show what files were installed:
2652

27-
::
53+
.. tabs::
54+
55+
.. group-tab:: Unix/macOS
56+
57+
.. code-block:: console
58+
59+
$ python -m pip show --files SomePackage
60+
Name: SomePackage
61+
Version: 1.0
62+
Location: /my/env/lib/pythonx.x/site-packages
63+
Files:
64+
../somepackage/__init__.py
65+
[...]
66+
67+
.. group-tab:: Windows
2868

29-
$ pip show --files SomePackage
30-
Name: SomePackage
31-
Version: 1.0
32-
Location: /my/env/lib/pythonx.x/site-packages
33-
Files:
34-
../somepackage/__init__.py
35-
[...]
69+
.. code-block:: console
70+
71+
C:\> py -m pip show --files SomePackage
72+
Name: SomePackage
73+
Version: 1.0
74+
Location: /my/env/lib/pythonx.x/site-packages
75+
Files:
76+
../somepackage/__init__.py
77+
[...]
3678
3779
List what packages are outdated:
3880

39-
::
81+
.. tabs::
82+
83+
.. group-tab:: Unix/macOS
84+
85+
.. code-block:: console
86+
87+
$ python -m pip list --outdated
88+
SomePackage (Current: 1.0 Latest: 2.0)
4089
41-
$ pip list --outdated
42-
SomePackage (Current: 1.0 Latest: 2.0)
90+
.. group-tab:: Windows
91+
92+
.. code-block:: console
93+
94+
C:\> py -m pip list --outdated
95+
SomePackage (Current: 1.0 Latest: 2.0)
4396
4497
Upgrade a package:
4598

46-
::
99+
.. tabs::
100+
101+
.. group-tab:: Unix/macOS
102+
103+
.. code-block:: console
47104
48-
$ pip install --upgrade SomePackage
49-
[...]
50-
Found existing installation: SomePackage 1.0
51-
Uninstalling SomePackage:
52-
Successfully uninstalled SomePackage
53-
Running setup.py install for SomePackage
54-
Successfully installed SomePackage
105+
$ python -m pip install --upgrade SomePackage
106+
[...]
107+
Found existing installation: SomePackage 1.0
108+
Uninstalling SomePackage:
109+
Successfully uninstalled SomePackage
110+
Running setup.py install for SomePackage
111+
Successfully installed SomePackage
112+
113+
.. group-tab:: Windows
114+
115+
.. code-block:: console
116+
117+
C:\> py -m pip install --upgrade SomePackage
118+
[...]
119+
Found existing installation: SomePackage 1.0
120+
Uninstalling SomePackage:
121+
Successfully uninstalled SomePackage
122+
Running setup.py install for SomePackage
123+
Successfully installed SomePackage
55124
56125
Uninstall a package:
57126

58-
::
127+
.. tabs::
128+
129+
.. group-tab:: Unix/macOS
130+
131+
.. code-block:: console
132+
133+
$ python -m pip uninstall SomePackage
134+
Uninstalling SomePackage:
135+
/my/env/lib/pythonx.x/site-packages/somepackage
136+
Proceed (y/n)? y
137+
Successfully uninstalled SomePackage
138+
139+
.. group-tab:: Windows
140+
141+
.. code-block:: console
59142
60-
$ pip uninstall SomePackage
61-
Uninstalling SomePackage:
62-
/my/env/lib/pythonx.x/site-packages/somepackage
63-
Proceed (y/n)? y
64-
Successfully uninstalled SomePackage
143+
C:\> py -m pip uninstall SomePackage
144+
Uninstalling SomePackage:
145+
/my/env/lib/pythonx.x/site-packages/somepackage
146+
Proceed (y/n)? y
147+
Successfully uninstalled SomePackage
65148
66149
67150
.. _PyPI: https://pypi.org/

0 commit comments

Comments
 (0)