Skip to content

Change to code-block:: text from code-block:: bash & update the version of pip #937

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Jul 12, 2021
Merged

Change to code-block:: text from code-block:: bash & update the version of pip #937

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
d90a975
Change to `text` from `bash` & update the version of pip
dukecat0 Jul 9, 2021
ede3fed
Remove `messages.pot` from this PR
dukecat0 Jul 9, 2021
d1ee5f6
Update source/guides/installing-using-pip-and-virtual-environments.rst
dukecat0 Jul 10, 2021
d1795e5
separate the command from its output
dukecat0 Jul 10, 2021
1394c76
Split which/where output
bhrutledge Jul 10, 2021
4e4adfd
Rework installing pip section
bhrutledge Jul 10, 2021
ee40d83
Use bat for Windows input
bhrutledge Jul 11, 2021
4e01f46
Use bash for Unix input
bhrutledge Jul 11, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions source/guides/distributing-packages-using-setuptools.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ Requirements for packaging and distributing

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install twine
Comment on lines +39 to 41
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For win console, it's probably just

Suggested change
.. code-block:: bat
py -m pip install twine
.. code-block:: doscon
> py -m pip install twine

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or maybe

Suggested change
.. code-block:: bat
py -m pip install twine
.. code-block:: ps1con
$ py -m pip install twine

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cc @bhrutledge have you seen these?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

D'oh. I missed those. I agree those seem appropriate, if there's a parallel change of all of the bash inputs, i.e.:

.. code-block:: console

    $ twine upload dist/*

I think that's beyond the scope of this PR. Also, as noted in an earlier discussion, I'm not sure it's a better experience, because it adds a little more work to copying a command.


Expand Down Expand Up @@ -728,7 +728,7 @@ Before you can build wheels and sdists for your project, you'll need to install

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install build

Expand All @@ -747,7 +747,7 @@ Minimally, you should create a :term:`Source Distribution <Source Distribution (

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m build --sdist

Expand Down Expand Up @@ -804,7 +804,7 @@ To build the wheel:

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m build --wheel

Expand Down Expand Up @@ -833,7 +833,7 @@ To build the wheel:

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m build --wheel

Expand Down Expand Up @@ -930,7 +930,7 @@ it will be automatically created when the first release is uploaded.
For the second and subsequent releases, PyPI only requires that the
version number of the new release differ from any previous releases.

.. code-block:: text
.. code-block:: bash

twine upload dist/*

Expand Down
2 changes: 1 addition & 1 deletion source/guides/dropping-older-python-versions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ Steps:

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install  --upgrade setuptools twine

Expand Down
2 changes: 1 addition & 1 deletion source/guides/hosting-your-own-index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ description to configure their installer appropriately. For example with pip:

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install --extra-index-url https://python.example.com/ foobar

Expand Down
83 changes: 50 additions & 33 deletions source/guides/installing-using-pip-and-virtual-environments.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,8 @@ installed.

.. tab:: Unix/macOS

Debian and most other distributions include a `python-pip`_ package, if you
want to use the Linux distribution-provided versions of pip see
Debian and most other distributions include a `python-pip`_ package; if you
want to use the Linux distribution-provided versions of pip, see
:doc:`/guides/installing-using-linux-tools`.

You can also install pip yourself to ensure you have the latest version. It's
Expand All @@ -32,30 +32,34 @@ installed.

python3 -m pip install --user --upgrade pip

Afterwards, you should have the newest pip installed in your user site:
python3 -m pip --version

.. code-block:: bash
Afterwards, you should have the latest version of pip installed in your
user site:

python3 -m pip --version
pip 9.0.1 from $HOME/.local/lib/python3.6/site-packages (python 3.6)
.. code-block:: text

pip 21.1.3 from $HOME/.local/lib/python3.9/site-packages (python 3.9)
Comment on lines +37 to +42
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In retrospect, the changes to this section probably should be in a separate PR, but I took the opportunity to (hopefully) add some additional clarity.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, also, the console session should be coupled with the output after the prompt input.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

coupled with the output after the prompt input

If you mean there shouldn't be any explanatory text between the input and the output code-block, I disagree. That's how it was in earlier commits, and I thought it was a bit confusing. Also, there are already places in this doc (and I assume others) where they are separated, e.g.:

https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#installing-packages

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's confusing when the input line isn't marked with a prompt. If it is, that should be rendered better.


.. _python-pip: https://packages.debian.org/stable/python-pip

.. tab:: Windows

The Python installers for Windows include pip. You should be able to access
pip using:
The Python installers for Windows include pip. You can make sure that pip is
up-to-date by running:

.. code-block:: bash
.. code-block:: bat

py -m pip install --upgrade pip

py -m pip --version
pip 9.0.1 from c:\python36\lib\site-packages (Python 3.6.1)

You can make sure that pip is up-to-date by running:
Afterwards, you should have the latest version of pip:

.. code-block:: bash
.. code-block:: text

pip 21.1.3 from c:\python39\lib\site-packages (Python 3.9.4)

py -m pip install --upgrade pip


Installing virtualenv
Expand All @@ -81,7 +85,7 @@ using pip.

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install --user virtualenv

Expand Down Expand Up @@ -111,7 +115,7 @@ in the below commands.

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m venv env

Expand Down Expand Up @@ -140,27 +144,40 @@ virtual environment-specific

.. tab:: Windows

.. code-block:: text
.. code-block:: bat

.\env\Scripts\activate

You can confirm you're in the virtual environment by checking the location of your
Python interpreter, it should point to the ``env`` directory.
Python interpreter:

.. tab:: Unix/macOS

.. code-block:: bash

which python
.../env/bin/python

.. tab:: Windows

.. code-block:: text
.. code-block:: bat

where python

It should be in the ``env`` directory:

.. tab:: Unix/macOS

.. code-block:: bash

.../env/bin/python

.. tab:: Windows

.. code-block:: bat

...\env\Scripts\python.exe


As long as your virtual environment is activated pip will install packages into that
specific environment and you'll be able to import and use packages in your
Python application.
Expand Down Expand Up @@ -193,7 +210,7 @@ Now that you're in your virtual environment you can install packages. Let's inst

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install requests

Expand Down Expand Up @@ -232,7 +249,7 @@ a specific version of ``requests``:

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install requests==2.18.4

Expand All @@ -246,7 +263,7 @@ To install the latest ``2.x`` release of requests:

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install requests>=2.0.0,<3.0.0

Expand All @@ -260,7 +277,7 @@ To install pre-release versions of packages, use the ``--pre`` flag:

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install --pre requests

Expand All @@ -279,7 +296,7 @@ specifying the extra in brackets:

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install requests[security]

Expand All @@ -301,7 +318,7 @@ pip can install a package directly from source, for example:

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

cd google-auth
py -m pip install .
Expand All @@ -318,7 +335,7 @@ installed package without needing to re-install:

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install --editable .

Expand Down Expand Up @@ -354,7 +371,7 @@ wheel, or tar file) you can install it directly with pip:

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install requests-2.18.4.tar.gz

Expand All @@ -370,7 +387,7 @@ pip to look for packages there and not to use the

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install --no-index --find-links=/local/dir/ requests

Expand All @@ -393,7 +410,7 @@ If you want to download packages from a different index than the

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install --index-url http://index.example.com/simple/ SomeProject

Expand All @@ -409,7 +426,7 @@ and a separate index, you can use the ``--extra-index-url`` flag instead:

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install --extra-index-url http://index.example.com/simple/ SomeProject

Expand All @@ -427,7 +444,7 @@ install the latest version of ``requests`` and all of its dependencies:

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install --upgrade requests

Expand All @@ -453,7 +470,7 @@ And tell pip to install all of the packages in this file using the ``-r`` flag:

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install -r requirements.txt

Expand All @@ -471,7 +488,7 @@ Pip can export a list of all installed packages and their versions using the

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip freeze

Expand Down
4 changes: 2 additions & 2 deletions source/guides/making-a-pypi-friendly-readme.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ such as ``text/plain``, ``text/x-rst`` (for reStructuredText), or ``text/markdow

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install --user --upgrade setuptools wheel twine

Expand Down Expand Up @@ -115,7 +115,7 @@ You can check your README for markup errors before uploading as follows:

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install --upgrade twine

Expand Down
4 changes: 2 additions & 2 deletions source/guides/using-testpypi.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ specifying the ``--index-url`` flag

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install --index-url https://test.pypi.org/simple/ your-package

Expand All @@ -65,7 +65,7 @@ you're testing has dependencies:

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple your-package

Expand Down
2 changes: 1 addition & 1 deletion source/tutorials/creating-documentation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Use ``pip`` to install Sphinx:

.. tab:: Windows

.. code-block:: bash
.. code-block:: bat

py -m pip install -U sphinx

Expand Down
Loading