Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork32.1k
[doc] Refresh the venv introduction documentation, and correct the statement about VIRTUAL_ENV (GH-98350)#98350
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.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Uh oh!
There was an error while loading.Please reload this page.
Conversation
ghost commentedOct 17, 2022 • edited by ghost
Loading Uh oh!
There was an error while loading.Please reload this page.
edited by ghost
Uh oh!
There was an error while loading.Please reload this page.
All commit authors signed the Contributor License Agreement. |
c11acb4 to54259a2Compare…orrect statement about the VIRTUAL_ENV environment variable
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. |
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.
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 |
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?
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 in1ba4797
bedevere-bot commentedOct 17, 2022
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 |
Phil, you need to sign the CLA using the button above. |
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 theFiles tab, clickingAdd to batch on each of the suggestions, and finally clickCommit 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!
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Doc/library/venv.rst Outdated
| .. 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: |
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.
| ..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 ofdistutils as an installer directly has been deprecated for perhaps a decade. Therefore, this should just be removed.
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. TheVIRTUAL_ENV environment variable documentation is wrong since Python 3.8 (by a commit that was backported that far 2 years ago).
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
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_ENVenvironment 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.
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 toVIRTUAL_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.
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.
As a quick reminder, to easily apply some or all of them with one click, go to theFiles tab, clickingAdd to batch on each of the suggestions, and finally clickCommit 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>
Sorry,@pelson and@vsajip, I could not cleanly backport this to |
CAM-Gerlach commentedOct 19, 2022 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
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 commit1a6bacb)
… the statement about VIRTUAL_ENV (pythonGH-98350)Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>(cherry picked from commit1a6bacb)
bedevere-bot commentedOct 19, 2022
GH-98465 is a backport of this pull request to the3.11 branch. |
bedevere-bot commentedOct 19, 2022
GH-98466 is a backport of this pull request to the3.10 branch. |
Yes, I've had a stab at it 🙂 |
Thanks@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 - |
* 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) ...
As documented in at the top of the SphinxRoles doc and in thePython 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 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 |
TIL - thanks! I'll look at updating those at some point. |
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 |
Remove the exclamation mark from :program:`!foo` in .rst files becauseit inadvertently shows up in the rendered HTML.(Sphinx's cross-referencing roles use a '!' prefix to suppresshyperlinking[1], but :program: is not a cross-referencing role so the'!' is displayed verbatim.)The exclamation marks in venv.rst were introduced in#98350. Seecomments [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 becauseit inadvertently shows up in the rendered HTML.(Sphinx's cross-referencing roles use a '!' prefix to suppresshyperlinking[1], but :program: is not a cross-referencing role so the'!' is displayed verbatim.)The exclamation marks in venv.rst were introduced inpython#98350. Seecomments [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 commit8647ba4)
Remove the exclamation mark from :program:`!foo` in .rst files becauseit inadvertently shows up in the rendered HTML.(Sphinx's cross-referencing roles use a '!' prefix to suppresshyperlinking[1], but :program: is not a cross-referencing role so the'!' is displayed verbatim.)The exclamation marks in venv.rst were introduced inpythonGH-98350. Seecomments [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-1286394047Reported-by: Vinay Sajip <vinay_sajip@yahoo.co.uk>.(cherry picked from commit8647ba4)Co-authored-by: Tom Levy <tomlevy93@gmail.com>
Remove the exclamation mark from :program:`!foo` in .rst files becauseit inadvertently shows up in the rendered HTML.(Sphinx's cross-referencing roles use a '!' prefix to suppresshyperlinking[1], but :program: is not a cross-referencing role so the'!' is displayed verbatim.)The exclamation marks in venv.rst were introduced inpythonGH-98350. Seecomments [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-1286394047Reported-by: Vinay Sajip <vinay_sajip@yahoo.co.uk>.(cherry picked from commit8647ba4)Co-authored-by: Tom Levy <tomlevy93@gmail.com>
Remove the exclamation mark from :program:`!foo` in .rst files becauseit inadvertently shows up in the rendered HTML.(Sphinx's cross-referencing roles use a '!' prefix to suppresshyperlinking[1], but :program: is not a cross-referencing role so the'!' is displayed verbatim.)The exclamation marks in venv.rst were introduced inpythonGH-98350. Seecomments [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-1286394047Reported-by: Vinay Sajip <vinay_sajip@yahoo.co.uk>.(cherry picked from commit8647ba4)Co-authored-by: Tom Levy <tomlevy93@gmail.com>
Done in#102694. |
…2716)Remove the exclamation mark from :program:`!foo` in .rst files becauseit inadvertently shows up in the rendered HTML.(Sphinx's cross-referencing roles use a '!' prefix to suppresshyperlinking[1], but :program: is not a cross-referencing role so the'!' is displayed verbatim.)The exclamation marks in venv.rst were introduced in#98350. Seecomments [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 becauseit inadvertently shows up in the rendered HTML.(Sphinx's cross-referencing roles use a '!' prefix to suppresshyperlinking[1], but :program: is not a cross-referencing role so the'!' is displayed verbatim.)The exclamation marks in venv.rst were introduced in#98350. Seecomments [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 becauseit inadvertently shows up in the rendered HTML.(Sphinx's cross-referencing roles use a '!' prefix to suppresshyperlinking[1], but :program: is not a cross-referencing role so the'!' is displayed verbatim.)The exclamation marks in venv.rst were introduced inpython#98350. Seecomments [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>
Remove the exclamation mark from :program:`!foo` in .rst files becauseit inadvertently shows up in the rendered HTML.(Sphinx's cross-referencing roles use a '!' prefix to suppresshyperlinking[1], but :program: is not a cross-referencing role so the'!' is displayed verbatim.)The exclamation marks in venv.rst were introduced inpython#98350. Seecomments [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>
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).