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

dukecat0 · 2021-07-09T07:23:36Z

pradyunsg · 2021-07-09T07:25:32Z

Hmm... This PR make me think that we should not checkin the .pot file, and instead generate that in a GitHub action instead.

dukecat0 · 2021-07-09T07:37:24Z

Hmm... This PR make me think that we should not checkin the .pot file, and instead generate that in a GitHub action instead.

Thanks for your suggestion and I will open another PR for this.

source/guides/distributing-packages-using-setuptools.rst

bhrutledge

Thanks for the comprehensive update! Beyond the question of text vs other lexers, just a couple some small tweaks to installing-using-pip-and-virtual-environments.rst for consistency.

source/guides/distributing-packages-using-setuptools.rst

bhrutledge · 2021-07-10T01:28:00Z

source/guides/installing-using-pip-and-virtual-environments.rst

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


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)

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

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

"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.

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.

@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

Co-authored-by: Brian Rutledge <brian@bhrutledge.com>

bhrutledge

Thanks for the changes. I pushed a couple more tweaks to the installing-using-pip doc.

Since this would be my first merge as a maintainer, I'll leave this open for another day to allow for more comments.

source/guides/distributing-packages-using-setuptools.rst

bhrutledge · 2021-07-10T13:45:20Z

source/guides/installing-using-pip-and-virtual-environments.rst

+
+It should be in the ``env`` directory:
+
+.. tab:: Unix/macOS
+
+    .. code-block:: text
+
+        .../env/bin/python
+
+.. tab:: Windows
+
+    .. code-block:: text
+
        ...\env\Scripts\python.exe


I thought having more distinction between the command and its output would read better.

bhrutledge · 2021-07-10T13:46:37Z

source/guides/installing-using-pip-and-virtual-environments.rst

+    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)


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.

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

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

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

dukecat0 · 2021-07-11T22:49:07Z

Thanks for @henryiii's suggestion and @bhrutledge's commits! :)

dukecat0 · 2021-07-12T06:30:24Z

@bhrutledge Do you think we should add copy button for folks so they can copy the command directly? It's very easy to do this( just add a sphinx extension). Btw, this could be added in another PR.

webknjaz · 2021-07-12T08:33:11Z

source/guides/distributing-packages-using-setuptools.rst

+        .. code-block:: bat

            py -m pip install twine


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

Or maybe

Suggested change

.. code-block:: bat

py -m pip install twine

.. code-block:: ps1con

$ py -m pip install twine

cc @bhrutledge have you seen these?

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.

bhrutledge

Thanks for the additional comments. I'm going to merge this as-is, because I think it's a nice improvement. Folks can follow up with additional issues/PRs if they like.

Do you think we should add copy button for folks so they can copy the command directly?

@meowmeowmeowcat That sounds handy. I'd probably start with a PR that just adds the button, but not the prompt characters and the configuration to remove it.

bhrutledge · 2021-07-12T09:24:09Z

source/guides/distributing-packages-using-setuptools.rst

+        .. code-block:: bat

            py -m pip install twine


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.

bhrutledge · 2021-07-12T09:30:21Z

source/guides/installing-using-pip-and-virtual-environments.rst

+    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)


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

webknjaz · 2021-07-12T09:51:41Z

re:copybutton — it'd be nice to integrate https://github.com/executablebooks/sphinx-copybutton + https://github.com/python/python-docs-theme/blob/master/python_docs_theme/static/copybutton.js

dukecat0 · 2021-07-12T09:53:57Z

re:copybutton — it'd be nice to integrate https://github.com/executablebooks/sphinx-copybutton + https://github.com/python/python-docs-theme/blob/master/python_docs_theme/static/copybutton.js

Thanks for this!

dukecat0 · 2021-07-12T10:58:07Z

https://github.com/python/python-docs-theme/blob/master/python_docs_theme/static/copybutton.js

@webknjaz Is this necessary for the docs? I think most of the code blocks in the docs are shell commands.

webknjaz · 2021-07-12T11:43:44Z

Dunno, I think it'd be nice to have the ability to easily copy those commands w/o the prompt.

dukecat0 · 2021-07-12T12:01:33Z

I agree. I will test sphinx-copybutton and see if it can integrate the function of the copybutton in python docs .

Change to text from bash & update the version of pip

d90a975

dukecat0 changed the title ~~Change to code-block :: text from code-block:: bash & update the version of pip~~ Change to code-block:: text from code-block:: bash & update the version of pip Jul 9, 2021

Remove messages.pot from this PR

ede3fed

ed738 approved these changes Jul 9, 2021

View reviewed changes

bhrutledge self-requested a review July 9, 2021 10:58

webknjaz reviewed Jul 9, 2021

View reviewed changes

source/guides/distributing-packages-using-setuptools.rst Outdated Show resolved Hide resolved

bhrutledge requested changes Jul 10, 2021

View reviewed changes

dukecat0 and others added 4 commits July 10, 2021 10:40

Update source/guides/installing-using-pip-and-virtual-environments.rst

d1ee5f6

Co-authored-by: Brian Rutledge <brian@bhrutledge.com>

separate the command from its output

d1795e5

Split which/where output

1394c76

Rework installing pip section

4e4adfd

bhrutledge approved these changes Jul 10, 2021

View reviewed changes

bhrutledge requested review from webknjaz and henryiii July 10, 2021 13:49

bhrutledge added 2 commits July 11, 2021 15:31

Use bat for Windows input

ee40d83

Use bash for Unix input

4e01f46

webknjaz reviewed Jul 12, 2021

View reviewed changes

bhrutledge approved these changes Jul 12, 2021

View reviewed changes

bhrutledge merged commit a95d0b1 into pypa:main Jul 12, 2021

dukecat0 deleted the Fixes-#934 branch July 12, 2021 09:46

dukecat0 mentioned this pull request Jul 12, 2021

Add Windows tab for some commands #942

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

dukecat0 commented Jul 9, 2021 •

edited by bhrutledge

Loading

pradyunsg commented Jul 9, 2021

dukecat0 commented Jul 9, 2021 •

edited

Loading

bhrutledge left a comment

bhrutledge Jul 10, 2021

bhrutledge Jul 10, 2021

webknjaz Jul 11, 2021

henryiii Jul 11, 2021 •

edited

Loading

bhrutledge Jul 11, 2021 •

edited

Loading

webknjaz Jul 12, 2021

bhrutledge left a comment

bhrutledge Jul 10, 2021

bhrutledge Jul 10, 2021

webknjaz Jul 12, 2021

bhrutledge Jul 12, 2021

webknjaz Jul 12, 2021

dukecat0 commented Jul 11, 2021 •

edited

Loading

dukecat0 commented Jul 12, 2021 •

edited

Loading

webknjaz Jul 12, 2021

webknjaz Jul 12, 2021

webknjaz Jul 12, 2021

bhrutledge Jul 12, 2021

bhrutledge left a comment

bhrutledge Jul 12, 2021

bhrutledge Jul 12, 2021

webknjaz commented Jul 12, 2021

dukecat0 commented Jul 12, 2021

dukecat0 commented Jul 12, 2021

webknjaz commented Jul 12, 2021

dukecat0 commented Jul 12, 2021

		.. code-block:: bash

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

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

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

Conversation

dukecat0 commented Jul 9, 2021 • edited by bhrutledge Loading

pradyunsg commented Jul 9, 2021

dukecat0 commented Jul 9, 2021 • edited Loading

bhrutledge left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

henryiii Jul 11, 2021 • edited Loading

Choose a reason for hiding this comment

bhrutledge Jul 11, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bhrutledge left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dukecat0 commented Jul 11, 2021 • edited Loading

dukecat0 commented Jul 12, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bhrutledge left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

webknjaz commented Jul 12, 2021

dukecat0 commented Jul 12, 2021

dukecat0 commented Jul 12, 2021

webknjaz commented Jul 12, 2021

dukecat0 commented Jul 12, 2021

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

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

dukecat0 commented Jul 9, 2021 •

edited by bhrutledge

Loading

dukecat0 commented Jul 9, 2021 •

edited

Loading

henryiii Jul 11, 2021 •

edited

Loading

bhrutledge Jul 11, 2021 •

edited

Loading

dukecat0 commented Jul 11, 2021 •

edited

Loading

dukecat0 commented Jul 12, 2021 •

edited

Loading