Restructure documentation sections to focus on new user experience (#4586)

Moving the preview features to top-level concepts and pushing the
pip-compatible interface down.

e.g.

<img width="291" alt="Screenshot 2024-06-27 at 7 03 48 AM"
src="500ad97d-899d-4051-b59d-e74786b3a45f">
This commit is contained in:
Zanie Blue 2024-07-02 12:44:45 -04:00 committed by GitHub
parent d05bb45c74
commit 12e12d066d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 69 additions and 63 deletions

View file

@ -7,17 +7,20 @@
- [Installing uv](installation.md) - [Installing uv](installation.md)
- [First steps](first-steps.md) - [First steps](first-steps.md)
# Basic concepts # Guides
- [Python environments](pip/environments.md) - [Installing Python](guides/install-python.md)
- [Managing packages](pip/packages.md) - [Running scripts](guides/scripts.md)
- [Inspecting packages](pip/inspection.md) - [Installing tools](guides/tools.md)
- [Declaring dependencies](pip/dependencies.md) - [Creating a project](guides/projects.md)
- [Locking environments](pip/compile.md)
# Advanced concepts # Concepts
- [Python discovery](python/discovery.md) - [Projects](preview/projects.md)
- [Command-line tools](preview/tools.md)
- [Python toolchains](preview/toolchains.md)
- [Workspaces](preview/workspaces.md)
- [Dependency sources](preview/dependencies.md)
- [Resolution](resolution.md) - [Resolution](resolution.md)
- [Caching](cache.md) - [Caching](cache.md)
- [Authentication](configuration/authentication.md) - [Authentication](configuration/authentication.md)
@ -33,14 +36,13 @@
- [Using in GitHub Actions](guides/github.md) - [Using in GitHub Actions](guides/github.md)
- [Using in pre-commit](guides/pre-commit.md) - [Using in pre-commit](guides/pre-commit.md)
# Preview features # Low-level operations
- [Introduction](preview/introduction.md) - [Using environments](pip/environments.md)
- [Projects](preview/projects.md) - [Managing packages](pip/packages.md)
- [Dependency specification](preview/dependencies.md) - [Inspecting packages](pip/inspection.md)
- [Workspaces](preview/workspaces.md) - [Declaring dependencies](pip/dependencies.md)
- [Command-line tools](preview/tools.md) - [Locking environments](pip/compile.md)
- [Python toolchains](preview/toolchains.md)
# Policies # Policies

View file

@ -0,0 +1 @@
# Installing Python

1
docs/guides/project.md Normal file
View file

@ -0,0 +1 @@
# Creating a project

1
docs/guides/projects.md Normal file
View file

@ -0,0 +1 @@
# Creating a project

1
docs/guides/scripts.md Normal file
View file

@ -0,0 +1 @@
# Running a script

1
docs/guides/tools.md Normal file
View file

@ -0,0 +1 @@
# Installing tools

View file

@ -87,3 +87,32 @@ If uv is installed in a Python environment, e.g., with `pip`, it can still be us
other environments. However, when invoked with `python -m uv`, uv will default to using the parent other environments. However, when invoked with `python -m uv`, uv will default to using the parent
interpreter's environment. Invoking uv via Python adds startup overhead and is not recommended for interpreter's environment. Invoking uv via Python adds startup overhead and is not recommended for
general usage. general usage.
uv itself does not depend on Python, but it does need to locate a Python environment to (1)
install dependencies into the environment and (2) build source distributions.
## Discovery of Python environments
When running a command that mutates an environment such as `uv pip sync` or `uv pip install`,
uv will search for a virtual environment in the following order:
- An activated virtual environment based on the `VIRTUAL_ENV` environment variable.
- An activated Conda environment based on the `CONDA_PREFIX` environment variable.
- A virtual environment at `.venv` in the current directory, or in the nearest parent directory.
If no virtual environment is found, uv will prompt the user to create one in the current
directory via `uv venv`.
If the `--system` flag is included, uv will skip virtual environments and search for:
- The Python interpreter available as `python3` on macOS and Linux, or `python.exe` on Windows.
- On Windows, the Python interpreter returned by `py --list-paths` that matches the requested
version.
If a specific Python version is requested, e.g., `--python 3.7`, additional executable names are included:
- The Python interpreter available as, e.g., `python3.7` on macOS and Linux.
When running a command that does not mutate the environment such as `uv pip compile`, uv does not
_require_ a virtual environment. Instead, it needs a Python toolchain to create ephemeral environments.
See the documentation on [toolchain discovery](./preview/toolchains.md#discovery-order) for details on discovery.

View file

@ -115,3 +115,16 @@ However, It's possible to adjust uv's toolchain selection preference with the `t
- `only-system`: Only use system toolchains, never use managed toolchains. - `only-system`: Only use system toolchains, never use managed toolchains.
These options allow disabling uv's managed toolchains entirely or always using them and ignoring any existing system installations. These options allow disabling uv's managed toolchains entirely or always using them and ignoring any existing system installations.
## Discovery order
When searching for a toolchain, the following locations are checked:
- Managed toolchains in the `UV_TOOLCHAIN_DIR`.
- A Python interpreter on the `PATH` as `python3` on macOS and Linux, or `python.exe` on Windows.
- On Windows, the Python interpreter returned by `py --list-paths` that matches the requested
version.
If a specific Python version is requested, e.g. `--python 3.7`, additional executable names are included in the search:
- A Python interpreter on the `PATH` as, e.g., `python3.7` on macOS and Linux.

View file

@ -1,45 +0,0 @@
# Python discovery
uv itself does not depend on Python, but it does need to locate a Python environment to (1)
install dependencies into the environment and (2) build source distributions.
## Environment mutating commands
When running a command that mutates an environment such as `uv pip sync` or `uv pip install`,
uv will search for a virtual environment in the following order:
- An activated virtual environment based on the `VIRTUAL_ENV` environment variable.
- An activated Conda environment based on the `CONDA_PREFIX` environment variable.
- A virtual environment at `.venv` in the current directory, or in the nearest parent directory.
If no virtual environment is found, uv will prompt the user to create one in the current
directory via `uv venv`.
If the `--system` flag is included, uv will skip virtual environments and search for:
- The Python interpreter available as `python3` on macOS and Linux, or `python.exe` on Windows.
- On Windows, the Python interpreter returned by `py --list-paths` that matches the requested
version.
## Commands that need an interpreter
When running a command that needs an interpreter but does not mutate the environment such as `uv pip compile`,
uv does not _require_ a virtual environment and will search for a Python interpreter in the following order:
- An activated virtual environment based on the `VIRTUAL_ENV` environment variable.
- An activated Conda environment based on the `CONDA_PREFIX` environment variable.
- A virtual environment at `.venv` in the current directory, or in the nearest parent directory.
- The Python interpreter available as `python3` on macOS and Linux, or `python.exe` on Windows.
If a `--python-version` is provided to `uv pip compile` (e.g., `--python-version=3.7`), uv will
search for a Python interpreter matching that version in the following order:
- An activated virtual environment based on the `VIRTUAL_ENV` environment variable.
- An activated Conda environment based on the `CONDA_PREFIX` environment variable.
- A virtual environment at `.venv` in the current directory, or in the nearest parent directory.
- The Python interpreter available as, e.g., `python3.7` on macOS and Linux.
- The Python interpreter available as `python3` on macOS and Linux, or `python.exe` on Windows.
- On Windows, the Python interpreter returned by `py --list-paths` that matches the requested
version.
These commands may create ephemeral virtual environments with the interpreter.

View file

@ -12,15 +12,17 @@ html {
} }
.chapter li.chapter-item { .chapter li.chapter-item {
margin-left: 1em; margin-left: 1em;
margin-block-start: 0.3em; margin-block-start: 0.2em;
font-weight: 300; font-weight: 300;
margin-block-end: 0.5em margin-block-end: 0.4em;
line-height: 1.2em;
font-size: 1.05em;
} }
.chapter li.chapter-item a:hover { .chapter li.chapter-item a:hover {
text-decoration: underline; text-decoration: underline;
} }
.chapter li.part-title { .chapter li.part-title {
margin: 10px 0 0px 0; margin: 0 0 0 0;
font-weight: 500; font-weight: 500;
font-size: 1.3em; font-size: 1.3em;
} }