docs(cli): document how to configure a custom source for "self update"

[sridhar-3009]

Summary

Addresses #10633.

Users in corporate or air-gapped environments cannot reach PyPI directly, so poetry self update fails without a way to specify a custom index. The documentation did not explain where or how to configure one.

What was missing

self update manages Poetry's own runtime environment using a separate pyproject.toml in Poetry's config directory (e.g. ~/.config/pypoetry/pyproject.toml), not the project's pyproject.toml. This is non-obvious and caused confusion.

Change

Added a "Custom sources for self update" subsection under ### self update that:

1. Explains that self update uses a separate pyproject.toml at Poetry's config directory.
2. Shows how to add a private source via poetry self add --source.
3. Mentions that the file can be edited directly like any other pyproject.toml.

Test plan

• Render docs locally and verify the subsection appears correctly under self update

[sourcery-ai]

Hey - I've left some high level feedback:

• Instead of hardcoding platform-specific config paths with "usually" wording, consider referencing the existing configuration directory documentation or mentioning the POETRY_CONFIG_DIR override so the guidance stays accurate across nonstandard setups.
• The example poetry self add --source my-mirror poetry assumes my-mirror is already defined; it may be clearer to either show how that source is configured or explicitly state that my-mirror must be an existing source in the self-managed pyproject.toml.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Instead of hardcoding platform-specific config paths with "usually" wording, consider referencing the existing configuration directory documentation or mentioning the `POETRY_CONFIG_DIR` override so the guidance stays accurate across nonstandard setups.
- The example `poetry self add --source my-mirror poetry` assumes `my-mirror` is already defined; it may be clearer to either show how that source is configured or explicitly state that `my-mirror` must be an existing source in the self-managed `pyproject.toml`.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}