Skip to content
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

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

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 2 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
10 changes: 5 additions & 5 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:: text

py -m pip install twine
bhrutledge marked this conversation as resolved.
Show resolved Hide resolved

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:: text

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:: text

py -m build --sdist

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

.. tab:: Windows

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

py -m build --wheel

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

.. tab:: Windows

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

py -m build --wheel

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:: text

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:: text

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

Expand Down
46 changes: 26 additions & 20 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 @@ -37,7 +37,10 @@ installed.
.. code-block:: bash

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

.. code-block:: bash

pip 21.1.3 from $HOME/.local/lib/python3.9/site-packages (python 3.9)
Copy link
Contributor

Choose a reason for hiding this comment

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

This isn't a bash command, but rather its output, so I think it should be text:

Suggested change
.. code-block:: bash
pip 21.1.3 from $HOME/.local/lib/python3.9/site-packages (python 3.9)
.. code-block:: text
pip 21.1.3 from $HOME/.local/lib/python3.9/site-packages (python 3.9)

Copy link
Contributor

Choose a reason for hiding this comment

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

Also, I think these blocks under "Activating Virtual Environments" should similarly separate the command from its output:

.. tab:: Unix/macOS

    .. code-block:: bash

        which python
        .../env/bin/python

.. tab:: Windows

    .. code-block:: text

        where python
        ...\env\Scripts\python.exe

Copy link
Member

Choose a reason for hiding this comment

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

I'm pretty sure it's console rather than text.

Copy link
Contributor

@henryiii henryiii Jul 11, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

"Text" removes all semantic meaning from the highlighting, promising you will never do better than text, and making it programmatically indistinguishable from a text output. I'd think bat or powershell would be better, as that's actually the language this is in, even if there's no current visual difference. console is supposed to be somewhat agnostic, even if bash-like - was it rendering incorrectly? Also, if they are struggling with output vs. input, what about:

    .. code-block:: bat

        where python

    .. code-block:: text

        ...\env\Scripts\python.exe

? Does that break it up too much? I used to have a "input" and "output" type (gitbook plugin, IIRC) that would handle this nicely. As long as we are consistent, it's easy to refactor in the future - going to "text" makes it harder, because there may really be some "text" blocks that are not Windows shell inputs.

Copy link
Contributor

@bhrutledge bhrutledge Jul 11, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

Those are good points re: semantics and refactoring, @henryiii. Since I was the one who originally suggested text, I just pushed the change to bat for Windows inputs (ee40d83), plus a couple remaining bash for Unix inputs (4e01f46).

I don't think console is correct for outputs, because according to the docs, it's a "lexer for Bash shell sessions, i.e. command lines, including a prompt, interspersed with output". text is widely-used throughout this project for outputs.

Copy link
Member

Choose a reason for hiding this comment

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

@bhrutledge I think I've seen console perform well with windows-based prompts. My understanding that it only highlights the lines starting with some sort of a prompt differently from those that don't.
But yes, looking at https://github.com/pygments/pygments/blob/1ea5fc3/pygments/lexers/shell.py#L226 and https://github.com/pygments/pygments/blob/1ea5fc3/pygments/lexers/shell.py#L556, it seems like doscon is a windows counterpart of the console lexer.

@henryiii I do think that having clear input (with prompt) + output coupled would be beneficial


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

Expand All @@ -46,14 +49,17 @@ installed.
The Python installers for Windows include pip. You should be able to access
pip using:

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

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

.. code-block:: text

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

You can make sure that pip is up-to-date by running:

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

py -m pip install --upgrade pip

Expand Down Expand Up @@ -81,7 +87,7 @@ using pip.

.. tab:: Windows

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

py -m pip install --user virtualenv

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

.. tab:: Windows

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

py -m venv env

Expand Down Expand Up @@ -193,7 +199,7 @@ Now that you're in your virtual environment you can install packages. Let's inst

.. tab:: Windows

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

py -m pip install requests

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

.. tab:: Windows

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

py -m pip install requests==2.18.4

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

.. tab:: Windows

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

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

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

.. tab:: Windows

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

py -m pip install --pre requests

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

.. tab:: Windows

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

py -m pip install requests[security]

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

.. tab:: Windows

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

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

.. tab:: Windows

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

py -m pip install --editable .

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

.. tab:: Windows

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

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

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

.. tab:: Windows

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

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

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

.. tab:: Windows

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

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

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

.. tab:: Windows

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

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

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

.. tab:: Windows

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

py -m pip install --upgrade requests

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

.. tab:: Windows

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

py -m pip install -r requirements.txt

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

.. tab:: Windows

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

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:: text

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:: text

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:: text

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:: text

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:: text

py -m pip install -U sphinx

Expand Down
Loading