GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — [doc] Refresh the venv introduction documentation, and correct the statement about VIRTUAL_ENV (GH-98350) by pelson · Pull Request #98350 · python/cpython

Conversation

@pelson

@pelson pelson commented Oct 17, 2022

Copy link
Copy Markdown
Contributor

Refresh the venv introduction documentation, and correct the incorrect statement about the VIRTUAL_ENV environment variable mentioned in #21970 (comment) in discussion with @vsajip.

This is quite an extensive restructure of the venv introduction. The existing documentation has clearly been developed iteratively, and it therefore needed a bit of effort to ensure that the information is presented logically and consistently. I am happy to adapt/adjust as requested, but I believe the proposed change is simpler, shorter and more precise.

In practice this documentation can be back-ported fully (it doesn't refer to any new features).

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@pelson
pelson requested a review from vsajip as a code owner October 17, 2022 08:41
@bedevere-bot bedevere-bot added the awaiting review label Oct 17, 2022
@pelson
pelson force-pushed the enh/venv-docs branch from 8c08a07 to b234ddc Compare October 17, 2022 08:41
@ghost

ghost commented Oct 17, 2022 •
edited by ghost
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown

All commit authors signed the Contributor License Agreement.
CLA signed

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@pelson
pelson force-pushed the enh/venv-docs branch 2 times, most recently from c11acb4 to 54259a2 Compare October 17, 2022 08:45
@pelson
Doc: Refresh the venv introduction documentation, and correct the inc…
ea6ccbe
…orrect statement about the VIRTUAL_ENV environment variable
@pelson
pelson force-pushed the enh/venv-docs branch from 54259a2 to ea6ccbe Compare October 17, 2022 08:47
@vsajip

vsajip commented Oct 17, 2022

Copy link
Copy Markdown
Member

Thanks, Phil, your changes look good to me. I'll ask for an additional reviewer to look at it, since I may be a bit too close to it to notice things from a newcomer's perspective.

pelson reacted with thumbs up emoji
All reactions
  • 👍 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@vsajip
vsajip requested a review from CAM-Gerlach October 17, 2022 10:15
@vsajip vsajip added docs Documentation in the Doc dir skip issue skip news labels Oct 17, 2022
vsajip
vsajip requested changes Oct 17, 2022
View reviewed changes

@vsajip vsajip left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Just a minor whitespace change.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
Comment thread Doc/library/venv.rst Outdated
be optionally isolated from the base's site packages, meaning
that packages installed in the base environment will not be accessible from
the virtual environment.
A virtual environment is therefore a powerful and convenient concept which

@vsajip vsajip Oct 17, 2022

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Perhaps insert a blank line here?

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

@pelson pelson Oct 17, 2022

Copy link
Copy Markdown
Contributor Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Sure thing. Done in 1ba4797

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@bedevere-bot bedevere-bot added awaiting changes and removed awaiting review labels Oct 17, 2022
@bedevere-bot

bedevere-bot commented Oct 17, 2022

Copy link
Copy Markdown

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@pelson
Review action to add newline into the documentation of virtual enviro…
1ba4797
…nments
@pelson
pelson force-pushed the enh/venv-docs branch from 27de904 to 1ba4797 Compare October 17, 2022 11:16
vsajip
vsajip approved these changes Oct 17, 2022
View reviewed changes
@bedevere-bot bedevere-bot added awaiting merge and removed awaiting changes labels Oct 17, 2022
@vsajip vsajip added awaiting review and removed awaiting merge labels Oct 17, 2022
@vsajip

vsajip commented Oct 17, 2022

Copy link
Copy Markdown
Member

Phil, you need to sign the CLA using the button above.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@CAM-Gerlach CAM-Gerlach added needs backport to 3.10 needs backport to 3.11 only security fixes labels Oct 17, 2022
CAM-Gerlach
CAM-Gerlach reviewed Oct 17, 2022
View reviewed changes

@CAM-Gerlach CAM-Gerlach left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

This is a significant improvement overall in the structure, presentation and phrasing of these docs. Thanks for all your work, @pelson !

I did have a number of comments, all as suggestions, that fix/clarify some key details, use appropriate Sphinx syntax, update or remove some outdated or inapplicable passages, say the same thing more simply and concisely, avoid repetition and improve phrasing.

To easily apply some or all of them with one click, go to the Files tab, clicking Add to batch on each of the suggestions, and finally click Commit once you've selected all the ones you want. You can also reply with your own suggestions and add/apply those at the same time, if you want to fix something in mine. That will apply the specific suggestions and auto-resolve the review comments all in one go, which makes things a lot easier for both you and us.

Thanks, and looking forward to seeing this merged!

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

pelson reacted with thumbs up emoji
All reactions
  • 👍 1 reaction
Comment thread Doc/library/venv.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/library/venv.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/library/venv.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/library/venv.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/library/venv.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/library/venv.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/library/venv.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/library/venv.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/library/venv.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/library/venv.rst Outdated
Comment on lines 130 to 136
.. note:: When a virtual environment is active, any options that change the
installation path will be ignored from all :mod:`distutils` configuration
files to prevent projects being inadvertently installed outside of the
virtual environment.


.. _venv-api:

@CAM-Gerlach CAM-Gerlach Oct 17, 2022

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Suggested change
.. note:: When a virtual environment is active, any options that change the
installation path will be ignored from all :mod:`distutils` configuration
files to prevent projects being inadvertently installed outside of the
virtual environment.
.. _venv-api:
.. _venv-api:

Distutils has been officially deprecated since Python 3.10 (the oldest backportable version) and removed in this version, 3.12 (thus the link should not resolve). Furthermore, use of these config files and use of distutils as an installer directly has been deprecated for perhaps a decade. Therefore, this should just be removed.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

@pelson pelson Oct 18, 2022

Copy link
Copy Markdown
Contributor Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

The one thing that would make me hesitate with this one is that it would be good to get these improvements into older Python docs. The VIRTUAL_ENV environment variable documentation is wrong since Python 3.8 (by a commit that was backported that far 2 years ago).

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

@vsajip vsajip Oct 18, 2022

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

But that snippet could be left out even in documentation for older Python versions, as it doesn't really add all that much information - for example, it's not clear which options might be meant in

any options that change the installation path

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

CAM-Gerlach reacted with thumbs up emoji
All reactions
  • 👍 1 reaction

@CAM-Gerlach CAM-Gerlach Oct 18, 2022

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

The one thing that would make me hesitate with this one is that it would be good to get these improvements into older Python docs.

Right, which is why I mentioned it has been deprecated since the oldest backportable version, Python 3.10, and discouraged for perhaps a decade (never mind "distutils configuration files"—I don't know if I've ever run into any modern mention of anything actually using them these days; I'm involved with a fair bit of packaging stuff and I'd never even heard of them until now). Ergo, this is likely to cause more confusion than anything, if even packaging experts like @vsajip aren't even sure what it is intended to mean. And if worst comes to worse, this one change can always be dropped in a backport (though it seems very unnecessary).

The VIRTUAL_ENV environment variable documentation is wrong since Python 3.8 (by a commit that was backported that far 2 years ago).

I'm not entirely sure what you intend to mean here, sorry.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

@pelson pelson Oct 19, 2022

Copy link
Copy Markdown
Contributor Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

I'm not entirely sure what you intend to mean here, sorry.

Simply stating that there is a factually incorrect statement in the documenation relating to VIRTUAL_ENV environment use (it claims: "This can be used to check if one is running inside a virtual environment.", which is wrong), which it would be great to remove from as many backported versions as possible to avoid incorrect usage in the wild.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

CAM-Gerlach reacted with thumbs up emoji
All reactions
  • 👍 1 reaction

@CAM-Gerlach CAM-Gerlach Oct 19, 2022

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Ah, gotcha 👍 I was confused and wasn't sure the connection.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@CAM-Gerlach

CAM-Gerlach commented Oct 17, 2022

Copy link
Copy Markdown
Member

As a quick reminder, to easily apply some or all of them with one click, go to the Files tab, clicking Add to batch on each of the suggestions, and finally click Commit once you've selected all the ones you want. You can also reply with your own suggestions and add/apply those at the same time, if you want to fix something in mine. That will apply the specific suggestions and auto-resolve the review comments all in one go, which makes things a lot easier for both you and us.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@pelson @CAM-Gerlach
Apply suggestions from code review
f3d13f3
Co-authored-by: C.A.M. Gerlach <[email protected]>
@miss-islington

miss-islington commented Oct 19, 2022

Copy link
Copy Markdown
Contributor

Sorry, @pelson and @vsajip, I could not cleanly backport this to 3.10 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 1a6bacb31f7b49c244a6cc3ff0fa7f71a82412ef 3.10

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@CAM-Gerlach

CAM-Gerlach commented Oct 19, 2022 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

Thanks @pelson for your hard work and putting up with me, and @vsajip for reviewing, inviting me to and merging!

@vsajip @pelson were either of you planning to do the manual cherry picking for the backport? If not, I can help take care of it, though I'm also pretty busy finishing #95913 before the 3.11 release Monday so it might not happen right away.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

vsajip pushed a commit to vsajip/cpython that referenced this pull request Oct 19, 2022
@pelson @CAM-Gerlach @vsajip
[doc] Refresh the venv introduction documentation, and correct the st…
b02b210
…atement about VIRTUAL_ENV (pythonGH-98350)

Co-authored-by: C.A.M. Gerlach <[email protected]>
(cherry picked from commit 1a6bacb)
@vsajip vsajip mentioned this pull request Oct 19, 2022
[3.11] [doc] Refresh the venv introduction documentation, and correct the st… (GH-98465) #98465
Merged
vsajip pushed a commit to vsajip/cpython that referenced this pull request Oct 19, 2022
@pelson @CAM-Gerlach @vsajip
[3.10] [doc] Refresh the venv introduction documentation, and correct…
4d2eb7b
… the statement about VIRTUAL_ENV (pythonGH-98350)

Co-authored-by: C.A.M. Gerlach <[email protected]>
(cherry picked from commit 1a6bacb)
@bedevere-bot

bedevere-bot commented Oct 19, 2022

Copy link
Copy Markdown

GH-98465 is a backport of this pull request to the 3.11 branch.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@bedevere-bot bedevere-bot removed the needs backport to 3.11 only security fixes label Oct 19, 2022
@vsajip vsajip mentioned this pull request Oct 19, 2022
[3.10] [doc] Refresh the venv introduction documentation, and correct… (GH-98466) #98466
Merged
@bedevere-bot

bedevere-bot commented Oct 19, 2022

Copy link
Copy Markdown

GH-98466 is a backport of this pull request to the 3.10 branch.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@bedevere-bot bedevere-bot removed the needs backport to 3.10 label Oct 19, 2022
@vsajip

vsajip commented Oct 19, 2022

Copy link
Copy Markdown
Member

were either of you planning to do the manual cherry picking for the backport?

Yes, I've had a stab at it 🙂

CAM-Gerlach reacted with hooray emoji
All reactions
  • 🎉 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@CAM-Gerlach

CAM-Gerlach commented Oct 20, 2022

Copy link
Copy Markdown
Member

Thanks @vsajip !

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@vsajip

vsajip commented Oct 20, 2022

Copy link
Copy Markdown
Member

I just looked at the built documentation and noticed something a bit odd.

ss82

I'm not familiar with the use of exclamation marks in this markup - :program:`!fish` and :program:`!csh` activation scripts. @CAM-Gerlach what do they do? I couldn't see anything in the Sphinx docs.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

carljm added a commit to carljm/cpython that referenced this pull request Oct 20, 2022
@carljm
Merge branch 'main' into typewatch
8bba5da
* main: (40 commits)
  pythongh-98461: Fix source location in comprehensions bytecode (pythonGH-98464)
  pythongh-98421: Clean Up PyObject_Print (pythonGH-98422)
  pythongh-98360: multiprocessing now spawns children on Windows with correct argv[0] in virtual environments (pythonGH-98462)
  CODEOWNERS: Become a typing code owner (python#98480)
  [doc] Improve logging cookbook example. (pythonGH-98481)
  Add more tkinter.Canvas tests (pythonGH-98475)
  pythongh-95023: Added os.setns and os.unshare functions (python#95046)
  pythonGH-98363: Presize the list for batched() (pythonGH-98419)
  pythongh-98374: Suppress ImportError for invalid query for help() command. (pythongh-98450)
  typing tests: `_overload_dummy` raises `NotImplementedError`, not `RuntimeError` (python#98351)
  pythongh-98354: Add unicode check for 'name' attribute in _imp_create_builtin (pythonGH-98412)
  pythongh-98257: Make _PyEval_SetTrace() reentrant (python#98258)
  pythongh-98414: py.exe launcher does not use defaults for -V:company/ option (pythonGH-98460)
  pythongh-98417: Store int_max_str_digits on the Interpreter State (pythonGH-98418)
  Doc: Remove title text from internal links (python#98409)
  [doc] Refresh the venv introduction documentation, and correct the statement about VIRTUAL_ENV (pythonGH-98350)
  Docs: Bump sphinx-lint and fix unbalanced inline literal markup (python#98441)
  pythongh-92886: Replace assertion statements in `handlers.BaseHandler` to support running with optimizations (`-O`) (pythonGH-93231)
  pythongh-92886: Fix tests that fail when running with optimizations (`-O`) in `_test_multiprocessing.py` (pythonGH-93233)
  pythongh-92886: Fix tests that fail when running with optimizations (`-O`) in `test_py_compile.py` (pythonGH-93235)
  ...
@CAM-Gerlach

CAM-Gerlach commented Oct 20, 2022

Copy link
Copy Markdown
Member

As documented in at the top of the Sphinx Roles doc and in the Python devguide, for any Sphinx role that creates a cross-reference (which are most of them), most domain-specific Sphinx roles) prefixing the content of with ! disables resolving the reference.

This is used in the CPython docs when the target is already referenced within the same paragraph/information unit to not link the same thing multiple times, when referring to a class, function etc. within its own description to avoid linking to itself, and when either the target intentionally doesn't exist (e.g. example class, removed from Python, not part of CPython, deliberately undocumented, etc) to skip wasting time looking it up and silence the resulting spurious warning.

I had naturally assumed that :program: was a cross-reference role that referenced programs defined by the .. program:: directive, just like :option: does for the .. option:: directive (that can be embedded inside .. program::, and I needed a ! since those programs weren't defined within the Python docs. However, it seems the role is in fact currently only for semantics/formatting purposes, and it does not support cross referencing. Therefore, the ! can simply be elided.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@vsajip

vsajip commented Oct 21, 2022

Copy link
Copy Markdown
Member

TIL - thanks! I'll look at updating those at some point.

CAM-Gerlach reacted with thumbs up emoji
All reactions
  • 👍 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@CAM-Gerlach

CAM-Gerlach commented Oct 21, 2022

Copy link
Copy Markdown
Member

Thanks! Since its my fault, I'll also look to take care of it at some point soon if you don't get to it first.

Also, I talked to Adam about adding cross-reference support to future Sphinx versions for :program:, so this might eventually work as intended.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@pelson
pelson deleted the enh/venv-docs branch October 30, 2022 21:07
@pelson pelson mentioned this pull request Nov 17, 2022
Implement config file location 'base' to config all environments of an interpreter pypa/pip#11487
Merged
@hugovk hugovk mentioned this pull request Mar 14, 2023
Remove misformatted exclamation marks in docs #102694
Merged
hugovk pushed a commit that referenced this pull request Mar 15, 2023
@tom93
Remove misformatted exclamation marks in docs (#102694)
8647ba4
Remove the exclamation mark from :program:`!foo` in .rst files because
it inadvertently shows up in the rendered HTML.

(Sphinx's cross-referencing roles use a '!' prefix to suppress
hyperlinking[1], but :program: is not a cross-referencing role so the
'!' is displayed verbatim.)

The exclamation marks in venv.rst were introduced in #98350. See
comments [2] and [3] for additional discussion.

[1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-syntax
[2]: #98350 (comment)
[3]: #98350 (comment)

Reported-by: Vinay Sajip <[email protected]>
hugovk pushed a commit to hugovk/cpython that referenced this pull request Mar 15, 2023
@tom93 @hugovk
Remove misformatted exclamation marks in docs (python#102694)
af00b09
Remove the exclamation mark from :program:`!foo` in .rst files because
it inadvertently shows up in the rendered HTML.

(Sphinx's cross-referencing roles use a '!' prefix to suppress
hyperlinking[1], but :program: is not a cross-referencing role so the
'!' is displayed verbatim.)

The exclamation marks in venv.rst were introduced in python#98350. See
comments [2] and [3] for additional discussion.

[1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-syntax
[2]: python#98350 (comment)
[3]: python#98350 (comment)

Reported-by: Vinay Sajip <[email protected]>
(cherry picked from commit 8647ba4)
hugovk added a commit to hugovk/cpython that referenced this pull request Mar 15, 2023
@hugovk @tom93
[3.11] Remove misformatted exclamation marks in docs (pythonGH-102694)
0f27753
Remove the exclamation mark from :program:`!foo` in .rst files because
it inadvertently shows up in the rendered HTML.

(Sphinx's cross-referencing roles use a '!' prefix to suppress
hyperlinking[1], but :program: is not a cross-referencing role so the
'!' is displayed verbatim.)

The exclamation marks in venv.rst were introduced in pythonGH-98350. See
comments [2] and [3] for additional discussion.

[1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.htmlGH-cross-referencing-syntax
[2]: https://github.com/python/cpython/pull/98350GH-issuecomment-1285965759
[3]: https://github.com/python/cpython/pull/98350GH-issuecomment-1286394047

Reported-by: Vinay Sajip <[email protected]>.
(cherry picked from commit 8647ba4)

Co-authored-by: Tom Levy <[email protected]>
hugovk pushed a commit to hugovk/cpython that referenced this pull request Mar 15, 2023
@tom93 @hugovk
[3.11] Remove misformatted exclamation marks in docs (pythonGH-102694)
71098e4
Remove the exclamation mark from :program:`!foo` in .rst files because
it inadvertently shows up in the rendered HTML.

(Sphinx's cross-referencing roles use a '!' prefix to suppress
hyperlinking[1], but :program: is not a cross-referencing role so the
'!' is displayed verbatim.)

The exclamation marks in venv.rst were introduced in pythonGH-98350. See
comments [2] and [3] for additional discussion.

[1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.htmlGH-cross-referencing-syntax
[2]: https://github.com/python/cpython/pull/98350GH-issuecomment-1285965759
[3]: https://github.com/python/cpython/pull/98350GH-issuecomment-1286394047

Reported-by: Vinay Sajip <[email protected]>.
(cherry picked from commit 8647ba4)

Co-authored-by: Tom Levy <[email protected]>
hugovk pushed a commit to hugovk/cpython that referenced this pull request Mar 15, 2023
@tom93 @hugovk
[3.10] Remove misformatted exclamation marks in docs (pythonGH-102694)
21691b0
Remove the exclamation mark from :program:`!foo` in .rst files because
it inadvertently shows up in the rendered HTML.

(Sphinx's cross-referencing roles use a '!' prefix to suppress
hyperlinking[1], but :program: is not a cross-referencing role so the
'!' is displayed verbatim.)

The exclamation marks in venv.rst were introduced in pythonGH-98350. See
comments [2] and [3] for additional discussion.

[1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.htmlGH-cross-referencing-syntax
[2]: https://github.com/python/cpython/pull/98350GH-issuecomment-1285965759
[3]: https://github.com/python/cpython/pull/98350GH-issuecomment-1286394047

Reported-by: Vinay Sajip <[email protected]>.
(cherry picked from commit 8647ba4)

Co-authored-by: Tom Levy <[email protected]>
@tom93

tom93 commented Mar 15, 2023

Copy link
Copy Markdown
Contributor

Therefore, the ! can simply be elided.

Done in #102694.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

hugovk added a commit that referenced this pull request Mar 15, 2023
@hugovk @tom93
[3.11] Remove misformatted exclamation marks in docs (GH-102694) (#10…
6b6c2f5
…2716)

Remove the exclamation mark from :program:`!foo` in .rst files because
it inadvertently shows up in the rendered HTML.

(Sphinx's cross-referencing roles use a '!' prefix to suppress
hyperlinking[1], but :program: is not a cross-referencing role so the
'!' is displayed verbatim.)

The exclamation marks in venv.rst were introduced in #98350. See
comments [2] and [3] for additional discussion.

[1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-syntax
[2]: #98350 (comment)
[3]: #98350 (comment)

Reported-by: Vinay Sajip <[email protected]>
Co-authored-by: Tom Levy <[email protected]>
hugovk added a commit that referenced this pull request Mar 15, 2023
@hugovk @tom93
[3.10] Remove misformatted exclamation marks in docs (GH-102694) (#10…
087fb56
…2717)

Remove the exclamation mark from :program:`!foo` in .rst files because
it inadvertently shows up in the rendered HTML.

(Sphinx's cross-referencing roles use a '!' prefix to suppress
hyperlinking[1], but :program: is not a cross-referencing role so the
'!' is displayed verbatim.)

The exclamation marks in venv.rst were introduced in #98350. See
comments [2] and [3] for additional discussion.

[1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-syntax
[2]: #98350 (comment)
[3]: #98350 (comment)

Reported-by: Vinay Sajip <[email protected]>
Co-authored-by: Tom Levy <[email protected]>
Fidget-Spinner pushed a commit to Fidget-Spinner/cpython that referenced this pull request Mar 27, 2023
@tom93 @Fidget-Spinner
Remove misformatted exclamation marks in docs (python#102694)
ff52779
Remove the exclamation mark from :program:`!foo` in .rst files because
it inadvertently shows up in the rendered HTML.

(Sphinx's cross-referencing roles use a '!' prefix to suppress
hyperlinking[1], but :program: is not a cross-referencing role so the
'!' is displayed verbatim.)

The exclamation marks in venv.rst were introduced in python#98350. See
comments [2] and [3] for additional discussion.

[1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-syntax
[2]: python#98350 (comment)
[3]: python#98350 (comment)

Reported-by: Vinay Sajip <[email protected]>
warsaw pushed a commit to warsaw/cpython that referenced this pull request Apr 11, 2023
@tom93 @warsaw
Remove misformatted exclamation marks in docs (python#102694)
9158524
Remove the exclamation mark from :program:`!foo` in .rst files because
it inadvertently shows up in the rendered HTML.

(Sphinx's cross-referencing roles use a '!' prefix to suppress
hyperlinking[1], but :program: is not a cross-referencing role so the
'!' is displayed verbatim.)

The exclamation marks in venv.rst were introduced in python#98350. See
comments [2] and [3] for additional discussion.

[1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-syntax
[2]: python#98350 (comment)
[3]: python#98350 (comment)

Reported-by: Vinay Sajip <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@CAM-Gerlach CAM-Gerlach CAM-Gerlach left review comments
@vsajip vsajip vsajip approved these changes

Uh oh!

There was an error while loading. Please reload this page.

Assignees

@vsajip vsajip

Labels

docs Documentation in the Doc dir skip issue skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

6 participants

@pelson @vsajip @bedevere-bot @CAM-Gerlach @miss-islington @tom93
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.