In preparation for a dedicated "Troubleshooting" section, revitalizes
the "Build failures" reference by adding more details, examples, and
structure. This will be used as a model for a "Install failures"
document.
- Adds a collapsible section for the project concept
- Splits the project concept document into several child documents.
- Moves the workspace and dependencies documents to under the project
section
- Adds a mkdocs plugin for redirects, so links to the moved documents
still work
I attempted to make the minimum required changes to the contents of the
documents here. There is a lot of room for improvement on the content of
each new child document. For review purposes, I want to do that work
separately. I'd prefer if the review focused on this structure and idea
rather than the content of the files.
I expect to do this to other documentation pages that would otherwise be
very nested.
The project concept landing page and nav (collapsed by default) looks
like this now:
<img width="1507" alt="Screenshot 2024-11-14 at 11 28 45 AM"
src="https://github.com/user-attachments/assets/88288b09-8463-49d4-84ba-ee27144b62a5">
## Summary
Now that we have all the pieces in place, this PR adds some dedicated
documentation to enable a variety of PyTorch setups.
This PR is downstream of #6523 and builds on the content in there; #6523
will merge first, and this PR will follow.
Hello there! First real docs PR for uv.
1. I expect this will be rewritten a gazillion times to have a
consistent tone with the rest of the docs, despite me trying to stick to
it as best as I could. Feel free to edit!
2. I went super on the verbose mode, while also providing a callout with
a TLDR on top. Scrap anything you feel it's redundant!
3. I placed the guide under `integrations` since Charlie added the
FastAPI integration there.
## Summary
<!-- What's the purpose of the change? What does it do, and why? -->
Addresses #5945
## Test Plan
<!-- How was it tested? -->
I just looked at the docs on the dev server of mkdocs if it looked nice.
**I could not test the commands that I wrote work** outside of macOS. If
someone among contributors has a Windows/Linux laptop, it should be
enough, even for the GPU-supported versions: I expect the installation
will just break once torch checks for CUDA (perhaps even at runtime).
---------
Co-authored-by: Santiago Castro <bryant1410@gmail.com>
Co-authored-by: Charlie Marsh <charlie.r.marsh@gmail.com>
## Summary
This PR adds a first-class API for defining registry indexes, beyond our
existing `--index-url` and `--extra-index-url` setup.
Specifically, you now define indexes like so in a `uv.toml` or
`pyproject.toml` file:
```toml
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"
```
You can also provide indexes via `--index` and `UV_INDEX`, and override
the default index with `--default-index` and `UV_DEFAULT_INDEX`.
### Index priority
Indexes are prioritized in the order in which they're defined, such that
the first-defined index has highest priority.
Indexes are also inherited from parent configuration (e.g., the
user-level `uv.toml`), but are placed after any indexes in the current
project, matching our semantics for other array-based configuration
values.
You can mix `--index` and `--default-index` with the legacy
`--index-url` and `--extra-index-url` settings; the latter two are
merely treated as unnamed `[[tool.uv.index]]` entries.
### Index pinning
If an index includes a name (which is optional), it can then be
referenced via `tool.uv.sources`:
```toml
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"
[tool.uv.sources]
torch = { index = "pytorch" }
```
If an index is marked as `explicit = true`, it can _only_ be used via
such references, and will never be searched implicitly:
```toml
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"
explicit = true
[tool.uv.sources]
torch = { index = "pytorch" }
```
Indexes defined outside of the current project (e.g., in the user-level
`uv.toml`) can _not_ be explicitly selected.
(As of now, we only support using a single index for a given
`tool.uv.sources` definition.)
### Default index
By default, we include PyPI as the default index. This remains true even
if the user defines a `[[tool.uv.index]]` -- PyPI is still used as a
fallback. You can mark an index as `default = true` to (1) disable the
use of PyPI, and (2) bump it to the bottom of the prioritized list, such
that it's used only if a package does not exist on a prior index:
```toml
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"
default = true
```
### Name reuse
If a name is reused, the higher-priority index with that name is used,
while the lower-priority indexes are ignored entirely.
For example, given:
```toml
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"
[[tool.uv.index]]
name = "pytorch"
url = "https://test.pypi.org/simple"
```
The `https://test.pypi.org/simple` index would be ignored entirely,
since it's lower-priority than `https://download.pytorch.org/whl/cu121`
but shares the same name.
Closes#171.
## Future work
- Users should be able to provide authentication for named indexes via
environment variables.
- `uv add` should automatically write `--index` entries to the
`pyproject.toml` file.
- Users should be able to provide multiple indexes for a given package,
stratified by platform:
```toml
[tool.uv.sources]
torch = [
{ index = "cpu", markers = "sys_platform == 'darwin'" },
{ index = "gpu", markers = "sys_platform != 'darwin'" },
]
```
- Users should be able to specify a proxy URL for a given index, to
avoid writing user-specific URLs to a lockfile:
```toml
[[tool.uv.index]]
name = "test"
url = "https://private.org/simple"
proxy = "http://<omitted>/pypi/simple"
```
<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:
- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->
## Summary
Documentation for GitLab integration, reliant on the new tags introduced
in https://github.com/astral-sh/uv/pull/6053
## Test Plan
<!-- How was it tested? -->
---------
Co-authored-by: David Fritzsche <9479371+davidfritzsche@users.noreply.github.com>
Co-authored-by: Zanie Blue <contact@zanie.dev>
## Summary
`mkdocs` supports [validation rules for
links](https://www.mkdocs.org/user-guide/configuration/#validation),
which can be tightened to report more issues than the default
configuration. I used the recommended "maximal strictness" configuration
from the documentation.
Adding the `anchors` rule helped spot 4 errors:
```console
WARNING - Doc file 'guides/install-python.md' contains a link '../concepts/python-versions.md#python-distributions', but the doc 'concepts/python-versions.md' does not contain an anchor '#python-distributions'.
WARNING - Doc file 'guides/install-python.md' contains a link '../concepts/python-versions.md#discovery-order', but the doc 'concepts/python-versions.md' does not contain an anchor '#discovery-order'.
WARNING - Doc file 'guides/projects.md' contains a link '../concepts/projects.md#lock-file', but the doc 'concepts/projects.md' does not contain an anchor '#lock-file'.
WARNING - Doc file 'pip/environments.md' contains a link '../concepts/python-versions.md#discovery-order', but the doc 'concepts/python-versions.md' does not contain an anchor '#discovery-order'.
```
## Test Plan
Local run of the documentation + `mkdocs build --strict`.
This PR rewrites the resolver concept and adds a resolver internals page
targeted at power users.
The new resolution concept documentation has three parts:
* An introduction for people how never heard of "resolution" before, and
a motivating example what it does. I've also shoved the part about
equally valid resolutions in there.
* Features you commonly use: Non-universal vs. universal resolution,
lowest resolution amd pre-releases.
* Expert features, we don't advertise them, you'll only need them in
complex cases when you already know and i kept them to the reference
points you need in this case: Constraints, overrides and exclude-newer.
I intentionally didn't lay out any detail of the resolution itself, the
idea is that users get a vague sense of "uv has to select fitting
versions", but then they learn the options they have to use and some
common failure points without ever coming near SAT or even graphs.
The resolution internals reference page is targeted at power users who
need to understand what is going on behind the scenes. It assumes ample
prior knowledge and exists to explain the uv-specific behaviors for
someone who already understands dependency resolution conceptually and
has interacted with their dependency tree before. I had a section on the
lockfile but removed it because it found the lockfile to be too
self-documenting.
I haven't touched the readme.
Closes#5603Closes#5238Closes#5237
---------
Co-authored-by: Zanie Blue <contact@zanie.dev>
