--without-scm-ignore-files (plural) was added inGH-83417: Allowvenv to add a.gitignore file to environments via a newscm_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 beforevenv. Elsewhere we only suggest.venv as the name, and the linkedPython Packaging Guide uses.venv in examples (the third-partyuv 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

hugovk added12 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.13bugs and security fixes labels

Sep 16, 2024

hugovk requested a review fromvsajip as acode 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

Copy link

MemberAuthor

hugovk commentedSep 16, 2024•
edited
Loading

Additionally,Doc/using/venv-create.inc is only included byDoc/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?

Copy link

Member

CAM-Gerlach commentedSep 20, 2024

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 reviewed

Sep 20, 2024

View reviewed changes

Copy link

Member

CAM-Gerlach left a comment•
edited
Loading

Choose a reason for hiding this comment

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

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

Doc/library/venv.rst OutdatedShow resolvedHide resolved

Doc/library/venv.rstShow resolvedHide resolved

Doc/using/venv-create.inc OutdatedShow resolvedHide resolved

Copy link

Member

vsajip commentedSep 21, 2024

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.

hugovkand others added2 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

Copy link

MemberAuthor

hugovk commentedSep 23, 2024

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

AA-Turner reviewed

Sep 23, 2024

View reviewed changes

Copy link

Member

AA-Turner left a comment

Choose a reason for hiding this comment

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

Brief read-through

Doc/library/venv.rst OutdatedShow resolvedHide resolved

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

Doc/library/venv.rst OutdatedShow resolvedHide resolved

bedevere-appbot added awaiting merge and removed awaiting core review labels

Sep 25, 2024

AA-Turner reviewed

Sep 25, 2024

View reviewed changes

Doc/library/venv.rst OutdatedShow resolvedHide resolved

Apply suggestions from code review

644a35b

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

hugovk merged commit23e812b intopython:main

Sep 26, 2024

23 checks passed

hugovk deleted the docs-update-venv branch

September 26, 2024 23:57

Copy link

miss-islington-appbot commentedSep 26, 2024

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

bedevere-appbot removed the awaiting merge label

Sep 26, 2024

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request

Sep 26, 2024

Docs: Update and proofreadlibrary/venv.rst(pythonGH-124121)

6b2e459

(cherry picked from commit23e812b)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>

Copy link

miss-islington-appbot commentedSep 26, 2024

Sorry,@hugovk, I could not cleanly backport this to3.12 due to a conflict.
Please backport usingcherry_picker on command line.

cherry_picker 23e812b84ae688a56a1011ed69a0d178c70e35ea 3.12

miss-islington-appbot assignedhugovk

Sep 26, 2024

Copy link

bedevere-appbot commentedSep 26, 2024

GH-124644 is a backport of this pull request to the3.13 branch.

bedevere-appbot removed the needs backport to 3.13bugs and security fixes label

Sep 26, 2024

hugovk added a commit to hugovk/cpython that referenced this pull request

Sep 27, 2024

[3.12] Docs: Update and proofreadlibrary/venv.rst(pythonGH-124121)

48ce591

(cherry picked from commit23e812b)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>

Copy link

bedevere-appbot commentedSep 27, 2024

GH-124680 is a backport of this pull request to the3.12 branch.

bedevere-appbot removed the needs backport to 3.12only security fixes label

Sep 27, 2024

Yhg1s pushed a commit that referenced this pull request

Sep 27, 2024

[3.13] Docs: Update and proofreadlibrary/venv.rst(GH-124121) (#12…

4c97ed4

…4644)Docs: Update and proofread `library/venv.rst` (GH-124121)(cherry picked from commit23e812b)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>

Yhg1s pushed a commit that referenced this pull request

Sep 30, 2024

[3.12] Docs: Update and proofreadlibrary/venv.rst(GH-124121) (#12…

0037717

…4680)* [3.12] Docs: Update and proofread `library/venv.rst` (GH-124121)(cherry picked from commit23e812b)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>

Labels

docs

Documentation in the Doc dir

skip issue skip news

4 participants

Movatterモバイル変換

Uh oh!

Docs: Update and proofreadlibrary/venv.rst#124121

Docs: Update and proofreadlibrary/venv.rst#124121

Uh oh!

Conversation

hugovk commentedSep 16, 2024• edited by AA-TurnerLoading Uh oh!There was an error while loading.Please reload this page.

Uh oh!

Uh oh!

hugovk commentedSep 16, 2024• editedLoading Uh oh!There was an error while loading.Please reload this page.

Uh oh!

Uh oh!

CAM-Gerlach commentedSep 20, 2024

Uh oh!

CAM-Gerlach left a comment• editedLoading 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 commentedSep 21, 2024

Uh oh!

hugovk commentedSep 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!

Uh oh!

miss-islington-appbot commentedSep 26, 2024

Uh oh!

miss-islington-appbot commentedSep 26, 2024

Uh oh!

bedevere-appbot commentedSep 26, 2024

Uh oh!

bedevere-appbot commentedSep 27, 2024

Uh oh!

Uh oh!

Docs: Update and proofread`library/venv.rst`#124121

Docs: Update and proofread`library/venv.rst`#124121

hugovk commentedSep 16, 2024•
edited by AA-Turner
Loading

hugovk commentedSep 16, 2024•
edited
Loading

CAM-Gerlach left a comment•
edited
Loading