[doc] Refresh the venv introduction documentation, and correct the statement about VIRTUAL_ENV (GH-98350)#98350

pelson

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

ghost

All commit authors signed the Contributor License Agreement.

…orrect statement about the VIRTUAL_ENV environment variable

vsajip

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.

vsajip

Just a minor whitespace change.

bedevere-bot

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.

…nments

vsajip

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

CAM-Gerlach

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!

CAM-Gerlach

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.

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

miss-islington

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

CAM-Gerlach

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.

…atement about VIRTUAL_ENV (pythonGH-98350) Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> (cherry picked from commit 1a6bacb)

… the statement about VIRTUAL_ENV (pythonGH-98350) Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> (cherry picked from commit 1a6bacb)

bedevere-bot

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

bedevere-bot

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

vsajip

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

Yes, I've had a stab at it 🙂

CAM-Gerlach

Thanks @vsajip !

vsajip

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

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.

* 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

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.

vsajip

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

CAM-Gerlach

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.

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 <vinay_sajip@yahoo.co.uk>

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 <vinay_sajip@yahoo.co.uk> (cherry picked from commit 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 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 <vinay_sajip@yahoo.co.uk>. (cherry picked from commit 8647ba4) Co-authored-by: Tom Levy <tomlevy93@gmail.com>

tom93

Therefore, the ! can simply be elided.

Done in #102694.

…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 <vinay_sajip@yahoo.co.uk> Co-authored-by: Tom Levy <tomlevy93@gmail.com>

…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 <vinay_sajip@yahoo.co.uk> Co-authored-by: Tom Levy <tomlevy93@gmail.com>

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 <vinay_sajip@yahoo.co.uk>

pelson requested a review from vsajip as a code owner October 17, 2022 08:41

bedevere-bot added the awaiting review label Oct 17, 2022

pelson force-pushed the enh/venv-docs branch from 8c08a07 to b234ddc Compare October 17, 2022 08:41

pelson force-pushed the enh/venv-docs branch 2 times, most recently from c11acb4 to 54259a2 Compare October 17, 2022 08:45

Doc: Refresh the venv introduction documentation, and correct the inc… …

ea6ccbe

…orrect statement about the VIRTUAL_ENV environment variable

pelson force-pushed the enh/venv-docs branch from 54259a2 to ea6ccbe Compare October 17, 2022 08:47

vsajip requested a review from CAM-Gerlach October 17, 2022 10:15

vsajip added docs Documentation in the Doc dir skip issue skip news labels Oct 17, 2022

vsajip requested changes Oct 17, 2022

View reviewed changes

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

Review action to add newline into the documentation of virtual enviro… …

1ba4797

…nments

pelson force-pushed the enh/venv-docs branch from 27de904 to 1ba4797 Compare October 17, 2022 11:16

vsajip approved these changes Oct 17, 2022

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting changes labels Oct 17, 2022

vsajip added awaiting review and removed awaiting merge labels Oct 17, 2022

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

CAM-Gerlach reviewed Oct 17, 2022

View reviewed changes

Apply suggestions from code review …

f3d13f3

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

vsajip mentioned this pull request Oct 19, 2022

[3.11] [doc] Refresh the venv introduction documentation, and correct the st… (GH-98465) #98465

Merged

bedevere-bot removed the needs backport to 3.11 only security fixes label Oct 19, 2022

vsajip mentioned this pull request Oct 19, 2022

[3.10] [doc] Refresh the venv introduction documentation, and correct… (GH-98466) #98466

Merged

bedevere-bot removed the only security fixes label Oct 19, 2022

pelson deleted the enh/venv-docs branch October 30, 2022 21:07

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 mentioned this pull request Mar 14, 2023

Remove misformatted exclamation marks in docs #102694

Merged

Conversation

pelson commented Oct 17, 2022

Uh oh!

ghost commented Oct 17, 2022 • edited by ghost Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vsajip commented Oct 17, 2022

Uh oh!

vsajip left a comment

Choose a reason for hiding this comment

Uh oh!

bedevere-bot commented Oct 17, 2022

Uh oh!

vsajip commented Oct 17, 2022

Uh oh!

CAM-Gerlach left a comment

Choose a reason for hiding this comment

Uh oh!

CAM-Gerlach commented Oct 17, 2022

Uh oh!

miss-islington commented Oct 19, 2022

Uh oh!

CAM-Gerlach commented Oct 19, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bedevere-bot commented Oct 19, 2022

Uh oh!

bedevere-bot commented Oct 19, 2022

Uh oh!

vsajip commented Oct 19, 2022

Uh oh!

CAM-Gerlach commented Oct 20, 2022

Uh oh!

vsajip commented Oct 20, 2022

Uh oh!

CAM-Gerlach commented Oct 20, 2022

Uh oh!

vsajip commented Oct 21, 2022

Uh oh!

CAM-Gerlach commented Oct 21, 2022

Uh oh!

tom93 commented Mar 15, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

ghost commented Oct 17, 2022 •

edited by ghost

Loading

CAM-Gerlach commented Oct 19, 2022 •

edited

Loading