Skip to content

docs: fix doubled backslashes in Windows pip config path - #1149

Merged
henryiii merged 2 commits into
pypa:mainfrom
aroh3006:docs/fix-windows-pip-config-path
Sep 4, 2026
Merged

docs: fix doubled backslashes in Windows pip config path#1149
henryiii merged 2 commits into
pypa:mainfrom
aroh3006:docs/fix-windows-pip-config-path

Conversation

@aroh3006

@aroh3006 aroh3006 commented Aug 12, 2026

Copy link
Copy Markdown
Contributor

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:

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 corporate-environments
This PR environment-variables corporate-environments

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
aroh3006 force-pushed the docs/fix-windows-pip-config-path branch from ff87f58 to fd65284 Compare August 12, 2026 21:48
Comment thread docs/changelog/1149.doc.rst Outdated
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`

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This is way too much for a minor docs mixup. :)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

makes sense. I'll keep the explanations shorter.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thanks!

@henryiii
henryiii merged commit 2369a40 into pypa:main Sep 4, 2026
10 checks passed
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)
|
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants