Docs: Update and proofread `library/venv.rst` by hugovk · Pull Request #124121 · python/cpython

hugovk · 2024-09-16T11:24:44Z

Content changes:

--without-scm-ignore-files (plural) was added in GH-83417: Allow venv to add a .gitignore file to environments via a new scm_ignore_file parameter #108125. When the PR was opened, it was --without-scm-ignore-file (singular) but changed to plural before merge. Some renamings were missed in the docs. Fix it now, and update the final help text.
pyvenv is documented as deprecated (3.6), but missing the removal (3.8). Document the removal.
Suggest .venv before venv. Elsewhere we only suggest .venv as the name, and the linked Python Packaging Guide uses .venv in examples (the third-party uv also defaults to .venv).

Everything else is proofreading and formatting, see individual commits for details.

This can be backported to 3.13 and 3.12, but 3.12 doesn't have --without-scm-ignore-files so will need a manual backport.

📚 Documentation preview 📚: https://cpython-previews--124121.org.readthedocs.build/en/124121/library/venv.html

…lp text

hugovk · 2024-09-16T12:02:18Z

Additionally, Doc/using/venv-create.inc is only included by Doc/library/venv.rst.

It might be worth moving the .inc contents into the .rst and deleting the .inc. One big benefit is IDE's are better at recognising .rst is reStructuredText and doing syntax highlighting and autocompletion, whereas .inc is shown as a monochrome plaintext file (PyCharm suggested plugins for PHP and Assembly...).

Another benefit is tooling such as Sphinx Lint primarily process .rst files.

What do you think?

CAM-Gerlach · 2024-09-20T20:59:26Z

It might be worth moving the .inc contents into the .rst and deleting the .inc. [...] What do you think?

Agreed; perhaps there once was a reason for it, e.g. being transcluded in some of the old packaging documentation that no longer exists here. Unless there is some need for it now that I'm missing, it seems worth eliminating the extra complexity.

CAM-Gerlach

Thanks @hugovk ! A handful of additional suggestions for you; otherwise LGTM 👍

vsajip · 2024-09-21T08:09:50Z

It might be worth moving the .inc contents into the .rst and deleting the .inc

Agreed. I think at one point it was just the output of the command line help (so you could replace updated help in it), but it's moved beyond that now.

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

hugovk · 2024-09-23T18:03:05Z

Thanks, I've moved the inc into the rst.

AA-Turner

Brief read-through

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

miss-islington-app · 2024-09-26T23:57:41Z

Thanks @hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13.
🐍🍒⛏🤖

(cherry picked from commit 23e812b) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

miss-islington-app · 2024-09-26T23:57:49Z

Sorry, @hugovk, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 23e812b84ae688a56a1011ed69a0d178c70e35ea 3.12

bedevere-app · 2024-09-26T23:57:51Z

GH-124644 is a backport of this pull request to the 3.13 branch.

(cherry picked from commit 23e812b) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

bedevere-app · 2024-09-27T16:41:53Z

GH-124680 is a backport of this pull request to the 3.12 branch.

…4644) Docs: Update and proofread `library/venv.rst` (GH-124121) (cherry picked from commit 23e812b) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

…4680) * [3.12] Docs: Update and proofread `library/venv.rst` (GH-124121) (cherry picked from commit 23e812b) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> * Remove 3.13 docs --------- Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

hugovk added 12 commits September 16, 2024 13:30

Suggest .venv before venv
4f8b2d5

Proofreading
8b96ad7

Document pyvenv was removed in 3.8
09d9bff

Fix without-scm-ignore-file -> without-scm-ignore-files option and he…
a490193
…lp text

Realign --help to match output
694c65d

Sort versionchanged oldest first, like elsewhere
fc04bdd

Highlight console commands
ead0426

Replace Latin abbreviation
f15cded

Code font for directory names
388351a

Git is the SCM, git is a command
552a786

Parameters in italics
76c6bcf

program formatting
2afa69d

hugovk added docs Documentation in the Doc dir needs backport to 3.13 bugs and security fixes labels Sep 16, 2024

hugovk requested a review from vsajip as a code owner September 16, 2024 11:24

bedevere-appBot added the awaiting core review label Sep 16, 2024

hugovk added needs backport to 3.12 only security fixes awaiting core review skip issue skip news and removed awaiting core review labels Sep 16, 2024

CAM-Gerlach reviewed Sep 20, 2024
View reviewed changes

hugovkand others added 2 commits September 23, 2024 20:55

Apply suggestions from code review
02e99ac
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

Move venv-create.inc into venv.rst
f664390

AA-Turner reviewed Sep 23, 2024
View reviewed changes

Comment threadDoc/library/venv.rst Outdated
Comment threadDoc/library/venv.rst Outdated
Comment threadDoc/library/venv.rst Outdated

Apply suggestions from code review
ca4ed66
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

Update Doc/library/venv.rst
90f0a63
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

AA-Turner approved these changes Sep 25, 2024
View reviewed changes

Comment threadDoc/library/venv.rst Outdated
Comment threadDoc/library/venv.rst Outdated

bedevere-appBot added awaiting merge and removed awaiting core review labels Sep 25, 2024

AA-Turner reviewed Sep 25, 2024
View reviewed changes

Comment threadDoc/library/venv.rst Outdated

Apply suggestions from code review
644a35b
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

hugovk merged commit 23e812b into python:mainSep 26, 2024

hugovk deleted the docs-update-venv branch September 26, 2024 23:57

bedevere-appBot removed the awaiting merge label Sep 26, 2024

miss-islington-appBot assigned hugovk Sep 26, 2024

bedevere-appBot removed the needs backport to 3.13 bugs and security fixes label Sep 26, 2024

bedevere-appBot removed the needs backport to 3.12 only security fixes label Sep 27, 2024

Uh oh!

Uh oh!

Conversation

hugovk commented Sep 16, 2024• edited by AA-Turner Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hugovk commented Sep 16, 2024• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CAM-Gerlach commented Sep 20, 2024

Uh oh!

CAM-Gerlach left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vsajip commented Sep 21, 2024

Uh oh!

hugovk commented Sep 23, 2024

Uh oh!

AA-Turner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

miss-islington-appBot commented Sep 26, 2024

Uh oh!

miss-islington-appBot commented Sep 26, 2024

Uh oh!

bedevere-appBot commented Sep 26, 2024

Uh oh!

bedevere-appBot commented Sep 27, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hugovk commented Sep 16, 2024•
edited by AA-Turner
Loading

hugovk commented Sep 16, 2024•
edited
Loading

CAM-Gerlach left a comment •
edited
Loading