Docs: clarify private deps require requirements.txt, not pyproject.toml

[ericholscher]

Summary

• Add FAQ entry: "How do I install private dependencies if my package uses pyproject.toml?"
• Add a note in the private Python packages guide clarifying that pip does not support environment variable expansion in pyproject.toml files
• Directs users to use requirements.txt for private dependencies instead

Per humitos suggestion in #10283:

a FAQ entry and just a small paragraph saying that is not supported by pip and they should use a requirements.txt file

Closes #10283

Test plan

• Verify the FAQ entry renders correctly in the built docs
• Verify the note in private-python-packages guide renders correctly
• Verify the seealso cross-reference link works

Made by AI

[read-the-docs-community]

Documentation build overview

📚 docs | 🛠️ Build #32053559 | 📁 Comparing 39b0a11 against latest (e3a4d81)

🔍 Preview build

Show files changed (4 files in total): 📝 4 modified | ➕ 0 added | ➖ 0 deleted

File	Status
downloadable-documentation.html	📝 modified
faq.html	📝 modified
user-defined-redirects.html	📝 modified
guides/private-python-packages.html	📝 modified

[humitos]

By the way, how does uv handles this? Now we are implementing support for it, we should know what to do there. In case uv already supports expanding env vars, we should probably mention it here as well.

[stsewd]

uv generates a lock file based on the deps from pyproject.toml, not sure if that changes how env vars expansion works.

Gemini says is best to just use ssh URLs, which we already have a note about

https://github.com/readthedocs/readthedocs.org/blob/main/docs/user/guides/private-python-packages.rst?plain=1#L23-L23

Alternative, there are some other ways to inject/pass extra credentials

uv has some docs that should also work with pip

• https://docs.astral.sh/uv/concepts/authentication/http/
• https://docs.astral.sh/uv/concepts/authentication/git/

[read-the-docs-community]

Documentation build overview

📚 dev | 🛠️ Build #32053558 | 📁 Comparing 39b0a11 against latest (e3a4d81)

🔍 Preview build

Show files changed (1 files in total): 📝 1 modified | ➕ 0 added | ➖ 0 deleted

File	Status
aws-temporary-credentials.html	📝 modified

[ericholscher]

I tried to add some uv copy, but didn't have time to actually test it, so figured it was better not to include it.

[stsewd]

I think we should mention using ssh URLs instead of telling users to change to a requirements file.