docs: fix doubled backslashes in Windows pip config path - #1149
Merged
Conversation
aroh3006
requested review from
gaborbernat,
henryiii and
layday
as code owners
August 12, 2026 21:48
Both places that give the Windows pip configuration file location write it with two backslashes per separator inside an inline literal. reStructuredText does not treat backslashes as escape characters inside inline literals, so they are rendered verbatim and readers of build.pypa.io are shown a path with doubled separators, which is not a valid path. pip's own documentation gives this location with single separators, and the surrounding docs already use single ones for Windows paths (for example the TEMP example in the same reference page). Verified by building the docs with "sphinx-build -W -n" and diffing the rendered HTML for both pages.
aroh3006
force-pushed
the
docs/fix-windows-pip-config-path
branch
from
August 12, 2026 21:48
ff87f58 to
fd65284
Compare
henryiii
reviewed
Aug 13, 2026
Comment on lines
+1
to
+3
| Write the Windows pip configuration path as ``%APPDATA%\pip\pip.ini`` in the environment variables reference and the | ||
| corporate environments how-to; the backslashes were doubled inside an inline literal, where reStructuredText does not | ||
| treat them as escapes, so the rendered docs showed an invalid path - by :user:`aroh3006` |
Contributor
There was a problem hiding this comment.
This is way too much for a minor docs mixup. :)
Contributor
Author
There was a problem hiding this comment.
makes sense. I'll keep the explanations shorter.
henryiii
approved these changes
Sep 4, 2026
henryiii
pushed a commit
that referenced
this pull request
Sep 9, 2026
### What was wrong Two pages give the location of pip's Windows configuration file, and both write the path with two backslashes per separator inside an inline literal: - `docs/reference/environment-variables.rst` — "Alternative: Configuration Files" - `docs/how-to/corporate-environments.rst` — "Configuration Files" reStructuredText does not treat backslashes as escape characters inside inline literals, so the doubled separators are rendered verbatim. Readers are shown a path with doubled separators, which is not a valid Windows path — anyone copying it to find or create their `pip.ini` gets the wrong location. This is visible on the published docs today, on both `stable` and `latest`: - <https://build.pypa.io/en/stable/reference/environment-variables.html> - <https://build.pypa.io/en/latest/how-to/corporate-environments.html> pip's own documentation gives this location with single separators (<https://pip.pypa.io/en/stable/topics/configuration/>), and the surrounding docs are already consistent with that — the `TEMP` example a few sections up in the same reference page uses single separators. ### How it was verified - Rendered the exact source lines through docutils before and after: the current source renders with doubled separators, the fixed source renders the correct path. - Built the full docs with the project's own settings, `sphinx-build -W -n -b html docs`, which **succeeded**, and diffed the generated HTML for both pages — each now renders the correct single-separator path. - Cross-checked against the live published pages (linked above) and against pip's documentation. - Confirmed `git grep` finds no other occurrence of the doubled form in the repository. ### What changed One line in each of the two files, changing the doubled separators in the inline literal to single ones. Nothing else — no prose, formatting, or unrelated files. ### Validation performed `sphinx-build -W -n` completed with no warnings or errors. I could not run the full `tox -e docs` environment locally (it pins `base_python = "3.14"`; I have 3.12), so `proselint` did not run — but this change touches no prose, only the contents of an inline literal. Happy to fold in the second file separately if you would rather keep the how-to and reference changes apart. ### Before / after on Read the Docs The Read the Docs preview for this PR renders the correct path on both pages, which can be compared directly against the currently published docs: | | Reference page | How-to page | |---|---|---| | Published today | [environment-variables](https://build.pypa.io/en/latest/reference/environment-variables.html) | [corporate-environments](https://build.pypa.io/en/latest/how-to/corporate-environments.html) | | This PR | [environment-variables](https://pypa-build--1149.org.readthedocs.build/en/1149/reference/environment-variables.html) | [corporate-environments](https://pypa-build--1149.org.readthedocs.build/en/1149/how-to/corporate-environments.html) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
What was wrong
Two pages give the location of pip's Windows configuration file, and both write the path with two backslashes per separator inside an inline literal:
docs/reference/environment-variables.rst— "Alternative: Configuration Files"docs/how-to/corporate-environments.rst— "Configuration Files"reStructuredText does not treat backslashes as escape characters inside inline literals, so the doubled separators are rendered verbatim. Readers are shown a path with doubled separators, which is not a valid Windows path — anyone copying it to find or create their
pip.inigets the wrong location.This is visible on the published docs today, on both
stableandlatest:pip's own documentation gives this location with single separators (https://pip.pypa.io/en/stable/topics/configuration/), and the surrounding docs are already consistent with that — the
TEMPexample a few sections up in the same reference page uses single separators.How it was verified
sphinx-build -W -n -b html docs, which succeeded, and diffed the generated HTML for both pages — each now renders the correct single-separator path.git grepfinds no other occurrence of the doubled form in the repository.What changed
One line in each of the two files, changing the doubled separators in the inline literal to single ones. Nothing else — no prose, formatting, or unrelated files.
Validation performed
sphinx-build -W -ncompleted with no warnings or errors. I could not run the fulltox -e docsenvironment locally (it pinsbase_python = "3.14"; I have 3.12), soproselintdid not run — but this change touches no prose, only the contents of an inline literal.Happy to fold in the second file separately if you would rather keep the how-to and reference changes apart.
Before / after on Read the Docs
The Read the Docs preview for this PR renders the correct path on both pages, which can be compared directly against the currently published docs: