Add structured documentation (#4426)

A ton of work remaining here, pushing so I can preview things rendered.

Here's the [latest rendered
documentation](https://astral-sh.github.io/uv/).

.github/workflows/docs.yml

@@ -2,7 +2,7 @@ name: Publish documentation
 
 on:
   push:
-    branches: ["zb/docs-i"]
+    branches: ["main"]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:

PIP_COMPATIBILITY.md

@@ -402,7 +402,3 @@ By default, uv does not write any index URLs to the output file, while `pip-comp
 `--index-url` or `--extra-index-url` that does not match the default (PyPI). To include index URLs
 in the output file, pass the `--emit-index-url` flag to `uv pip compile`. Unlike `pip-compile`,
 uv will include all index URLs when `--emit-index-url` is passed, including the default index URL.
-
-By default, uv does not write any `--no-build` or `--only-binary` options to the output file, unlike
-`pip-compile`. To include these options in the output file, pass the `--emit-build-options` flag to
-`uv pip compile`.

docs/.gitignore

@@ -0,0 +1 @@
+book

docs/SUMMARY.md

@@ -0,0 +1,49 @@
+# Summary
+
+- [Introduction](introduction.md)
+
+# Getting started
+
+- [Installing uv](installation.md)
+- [First steps](first-steps.md)
+
+# Basic concepts
+
+- [Python environments](pip/environments.md)
+- [Managing packages](pip/packages.md)
+- [Inspecting packages](pip/inspection.md)
+- [Declaring dependencies](pip/dependencies.md)
+- [Locking environments](pip/compile.md)
+
+# Advanced concepts
+
+- [Python discovery](python/discovery.md)
+- [Resolution](resolution.md)
+- [Caching](cache.md)
+- [Authentication](configuration/authentication.md)
+
+# Configuration
+
+- [Configuration files](configuration/files.md)
+- [Environment variables](configuration/environment.md)
+
+# Integration guides
+
+- [Using in Docker](guides/docker.md)
+- [Using in GitHub Actions](guides/github.md)
+- [Using in pre-commit](guides/pre-commit.md)
+
+# Preview features
+
+- [Introduction](preview/introduction.md)
+- [Projects](preview/projects.md)
+- [Dependency specification](preview/dependencies.md)
+- [Workspaces](preview/workspaces.md)
+- [Command-line tools](preview/tools.md)
+- [Python toolchains](preview/toolchains.md)
+
+# Policies
+
+- [Versioning](versioning.md)
+- [Platform support](platforms.md)
+- [Compatibility with pip](pip/compatibility.md)

docs/book.toml

@@ -0,0 +1,9 @@
+[book]
+language = "en"
+multilingual = false
+src = "."
+title = "uv"
+
+[output.html]
+no-section-label = true
+additional-css = ["style.css"]

docs/cache.md

@@ -0,0 +1,34 @@
+# Caching
+
+## Dependency caching
+
+uv uses aggressive caching to avoid re-downloading (and re-building dependencies) that have
+already been accessed in prior runs.
+
+The specifics of uv's caching semantics vary based on the nature of the dependency:
+
+- **For registry dependencies** (like those downloaded from PyPI), uv respects HTTP caching headers.
+- **For direct URL dependencies**, uv respects HTTP caching headers, and also caches based on
+  the URL itself.
+- **For Git dependencies**, uv caches based on the fully-resolved Git commit hash. As such,
+  `uv pip compile` will pin Git dependencies to a specific commit hash when writing the resolved
+  dependency set.
+- **For local dependencies**, uv caches based on the last-modified time of the source archive (i.e.,
+  the local `.whl` or `.tar.gz` file). For directories, uv caches based on the last-modified time of
+  the `pyproject.toml`, `setup.py`, or `setup.cfg` file.
+
+It's safe to run multiple `uv` commands concurrently, even against the same virtual environment.
+uv's cache is designed to be thread-safe and append-only, and thus robust to multiple concurrent
+readers and writers. uv applies a file-based lock to the target virtual environment when installing,
+to avoid concurrent modifications across processes.
+
+Note that it's _not_ safe to modify the uv cache directly (e.g., `uv cache clean`) while other `uv`
+commands are running, and _never_ safe to modify the cache directly (e.g., by removing a file or
+directory).
+
+If you're running into caching issues, uv includes a few escape hatches:
+
+- To force uv to revalidate cached data for all dependencies, run `uv pip install --refresh ...`.
+- To force uv to revalidate cached data for a specific dependency, run, e.g., `uv pip install --refresh-package flask ...`.
+- To force uv to ignore existing installed versions, run `uv pip install --reinstall ...`.
+- To clear the global cache entirely, run `uv cache clean`.

docs/configuration/authentication.md

@@ -0,0 +1,68 @@
+# Authentication
+
+## Git authentication
+
+uv allows packages to be installed from Git and supports the following schemes for authenticating with private
+repositories.
+
+Using SSH:
+
+- `git+ssh://git@<hostname>/...` (e.g. `git+ssh://git@github.com/astral-sh/uv`)
+- `git+ssh://git@<host>/...` (e.g. `git+ssh://git@git.luolix.top-key-2/astral-sh/uv`)
+
+See the [GitHub SSH documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh) for more details on how to configure SSH.
+
+Using a password or token:
+
+- `git+https://<user>:<token>@<hostname>/...` (e.g. `git+https://git:github_pat_asdf@github.com/astral-sh/uv`)
+- `git+https://<token>@<hostname>/...` (e.g. `git+https://github_pat_asdf@github.com/astral-sh/uv`)
+- `git+https://<user>@<hostname>/...` (e.g. `git+https://git@github.com/astral-sh/uv`)
+
+When using a GitHub personal access token, the username is arbitrary. GitHub does not support logging in with password directly, although other hosts may. If a username is provided without credentials, you will be prompted to enter them.
+
+If there are no credentials present in the URL and authentication is needed, the [Git credential helper](https://git-scm.com/doc/credential-helpers) will be queried.
+
+## HTTP authentication
+
+uv supports credentials over HTTP when querying package registries.
+
+Authentication can come from the following sources, in order of precedence:
+
+- The URL, e.g., `https://<user>:<password>@<hostname>/...`
+- A [`netrc`](https://everything.curl.dev/usingcurl/netrc) configuration file
+- A [keyring](https://github.com/jaraco/keyring) provider (requires opt-in)
+
+If authentication is found for a single net location (scheme, host, and port), it will be cached for the duration
+of the command and used for other queries to that net location. Authentication is not cached across invocations of
+uv.
+
+Note `--keyring-provider subprocess` or `UV_KEYRING_PROVIDER=subprocess` must be provided to enable keyring-based
+authentication.
+
+Authentication may be used for hosts specified in the following contexts:
+
+- `index-url`
+- `extra-index-url`
+- `find-links`
+- `package @ https://...`
+
+See the [`pip` compatibility guide](./pip/compatibility.md#registry-authentication) for details on differences from
+`pip`.
+
+## Custom CA certificates
+
+By default, uv loads certificates from the bundled `webpki-roots` crate. The `webpki-roots` are a
+reliable set of trust roots from Mozilla, and including them in uv improves portability and
+performance (especially on macOS, where reading the system trust store incurs a significant delay).
+
+However, in some cases, you may want to use the platform's native certificate store, especially if
+you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your
+system's certificate store. To instruct uv to use the system's trust store, run uv with the
+`--native-tls` command-line flag, or set the `UV_NATIVE_TLS` environment variable to `true`.
+
+If a direct path to the certificate is required (e.g., in CI), set the `SSL_CERT_FILE` environment
+variable to the path of the certificate bundle, to instruct uv to use that file instead of the
+system's trust store.
+
+If client certificate authentication (mTLS) is desired, set the `SSL_CLIENT_CERT` environment
+variable to the path of the PEM formatted file containing the certificate followed by the private key.

docs/configuration/environment.md

@@ -0,0 +1,87 @@
+# Environment variables
+
+uv accepts the following command-line arguments as environment variables:
+
+- `UV_INDEX_URL`: Equivalent to the `--index-url` command-line argument. If set, uv will use this
+  URL as the base index for searching for packages.
+- `UV_EXTRA_INDEX_URL`: Equivalent to the `--extra-index-url` command-line argument. If set, uv
+  will use this space-separated list of URLs as additional indexes when searching for packages.
+- `UV_CACHE_DIR`: Equivalent to the `--cache-dir` command-line argument. If set, uv will use this
+  directory for caching instead of the default cache directory.
+- `UV_NO_CACHE`: Equivalent to the `--no-cache` command-line argument. If set, uv will not use the
+  cache for any operations.
+- `UV_RESOLUTION`: Equivalent to the `--resolution` command-line argument. For example, if set to
+  `lowest-direct`, uv will install the lowest compatible versions of all direct dependencies.
+- `UV_PRERELEASE`: Equivalent to the `--prerelease` command-line argument. For example, if set to
+  `allow`, uv will allow pre-release versions for all dependencies.
+- `UV_SYSTEM_PYTHON`: Equivalent to the `--system` command-line argument. If set to `true`, uv
+  will use the first Python interpreter found in the system `PATH`.
+  WARNING: `UV_SYSTEM_PYTHON=true` is intended for use in continuous integration (CI) or
+  containerized environments and should be used with caution, as modifying the system Python
+  can lead to unexpected behavior.
+- `UV_PYTHON`: Equivalent to the `--python` command-line argument. If set to a path, uv will
+  use this Python interpreter for all operations.
+- `UV_BREAK_SYSTEM_PACKAGES`: Equivalent to the `--break-system-packages` command-line argument. If
+  set to `true`, uv will allow the installation of packages that conflict with system-installed
+  packages.
+  WARNING: `UV_BREAK_SYSTEM_PACKAGES=true` is intended for use in continuous integration (CI) or
+  containerized environments and should be used with caution, as modifying the system Python
+  can lead to unexpected behavior.
+- `UV_NATIVE_TLS`: Equivalent to the `--native-tls` command-line argument. If set to `true`, uv
+  will use the system's trust store instead of the bundled `webpki-roots` crate.
+- `UV_INDEX_STRATEGY`: Equivalent to the `--index-strategy` command-line argument. For example, if
+  set to `unsafe-any-match`, uv will consider versions of a given package available across all
+  index URLs, rather than limiting its search to the first index URL that contains the package.
+- `UV_REQUIRE_HASHES`: Equivalent to the `--require-hashes` command-line argument. If set to `true`,
+  uv will require that all dependencies have a hash specified in the requirements file.
+- `UV_CONSTRAINT`: Equivalent to the `--constraint` command-line argument. If set, uv will use this
+  file as the constraints file. Uses space-separated list of files.
+- `UV_LINK_MODE`: Equivalent to the `--link-mode` command-line argument. If set, uv will use this
+  as a link mode.
+- `UV_NO_BUILD_ISOLATION`: Equivalent to the `--no-build-isolation` command-line argument. If set,
+  uv will skip isolation when building source distributions.
+- `UV_CUSTOM_COMPILE_COMMAND`: Used to override `uv` in the output header of the `requirements.txt`
+  files generated by `uv pip compile`. Intended for use-cases in which `uv pip compile` is called
+  from within a wrapper script, to include the name of the wrapper script in the output file.
+- `UV_KEYRING_PROVIDER`: Equivalent to the `--keyring-provider` command-line argument. If set, uv
+  will use this value as the keyring provider.
+- `UV_CONFIG_FILE`: Equivalent to the `--config-file` command-line argument. Expects a path to a
+  local `uv.toml` file to use as the configuration file.
+- `UV_CONCURRENT_DOWNLOADS`: Sets the maximum number of in-flight concurrent downloads that `uv`
+  will perform at any given time.
+- `UV_CONCURRENT_BUILDS`: Sets the maximum number of source distributions that `uv` will build
+  concurrently at any given time.
+- `UV_CONCURRENT_INSTALLS`: Used to control the number of threads used when installing and unzipping
+  packages.
+- `UV_EXCLUDE_NEWER`: Equivalent to the `--exclude-newer` command-line argument. If set, uv will
+  exclude distributions published after the specified date.
+
+In each case, the corresponding command-line argument takes precedence over an environment variable.
+
+In addition, uv respects the following environment variables:
+
+- `SSL_CERT_FILE`: If set, uv will use this file as the certificate bundle instead of the system's
+  trust store.
+- `SSL_CLIENT_CERT`: If set, uv will use this file for mTLS authentication. This should be a single
+  file containing both the certificate and the private key in PEM format.
+- `RUST_LOG`: If set, uv will use this value as the log level for its `--verbose` output. Accepts
+  any filter compatible with the `tracing_subscriber` crate. For example, `RUST_LOG=trace` will
+  enable trace-level logging. See the [tracing documentation](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax)
+  for more.
+- `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`: The proxy to use for all HTTP/HTTPS requests.
+- `HTTP_TIMEOUT` (or `UV_HTTP_TIMEOUT`): If set, uv will use this value (in seconds) as the timeout
+  for HTTP reads (default: 30 s).
+- `PYC_INVALIDATION_MODE`: The validation modes to use when run with `--compile`.
+  See: [`PycInvalidationMode`](https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode).
+- `VIRTUAL_ENV`: Used to detect an activated virtual environment.
+- `CONDA_PREFIX`: Used to detect an activated Conda environment.
+- `PROMPT`: Used to detect the use of the Windows Command Prompt (as opposed to PowerShell).
+- `NU_VERSION`: Used to detect the use of NuShell.
+- `FISH_VERSION`: Used to detect the use of the Fish shell.
+- `BASH_VERSION`: Used to detect the use of the Bash shell.
+- `ZSH_VERSION`: Used to detect the use of the Zsh shell.
+- `MACOSX_DEPLOYMENT_TARGET`: Used with `--python-platform macos` and related variants to set the
+  deployment target (i.e., the minimum supported macOS version). Defaults to `12.0`, the
+  least-recent non-EOL macOS version at time of writing.
+- `NO_COLOR`: Disable colors. Takes precedence over `FORCE_COLOR`. See [no-color.org](https://no-color.org).
+- `FORCE_COLOR`: Enforce colors regardless of TTY support. See [force-color.org](https://force-color.org).

docs/configuration/files.md

@@ -0,0 +1,45 @@
+# Configuration files
+
+uv supports persistent configuration files at both the project- and user-level.
+
+Specifically, uv will search for a `pyproject.toml` or `uv.toml` file in the current directory, or
+in the nearest parent directory.
+
+If a `pyproject.toml` file is found, uv will read configuration from the `[tool.uv.pip]` table.
+For example, to set a persistent index URL, add the following to a `pyproject.toml`:
+
+```toml
+[tool.uv.pip]
+index-url = "https://test.pypi.org/simple"
+```
+
+(If there is no such table, the `pyproject.toml` file will be ignored, and uv will continue searching in
+the directory hierarchy.)
+
+If a `uv.toml` file is found, uv will read from the `[pip]` table. For example:
+
+```toml
+[pip]
+index-url = "https://test.pypi.org/simple"
+```
+
+uv will also discover user-level configuration at `~/.config/uv/uv.toml` (or
+`$XDG_CONFIG_HOME/uv/uv.toml`) on macOS and Linux, or `%APPDATA%\uv\uv.toml` on Windows. User-level
+configuration must use the `uv.toml` format, rather than the `pyproject.toml` format, as a
+`pyproject.toml` is intended to define a Python _project_.
+
+If both project- and user-level configuration are found, the settings will be merged, with the
+project-level configuration taking precedence. Specifically, if a string, number, or boolean is
+present in both tables, the project-level value will be used, and the user-level value will be
+ignored. If an array is present in both tables, the arrays will be concatenated, with the
+project-level settings appearing earlier in the merged array.
+
+Settings provided via environment variables take precedence over persistent configuration, and
+settings provided via the command line take precedence over both.
+
+uv accepts a `--isolated` command-line argument which, when provided, disables the discovery of any
+persistent configuration.
+
+uv also accepts a `--config-file` command-line argument, which accepts a path to a `uv.toml` to use
+as the configuration file. When provided, this file will be used in place of _any_ discovered
+configuration files (e.g., user-level configuration will be ignored).

docs/first-steps.md

@@ -0,0 +1,72 @@
+# First steps with uv
+
+## Check the version
+
+After [installing uv](./installation.md), check that it works from the CLI:
+
+```bash
+uv version
+```
+
+The installed version should be displayed.
+
+## uv's interfaces
+
+uv's commands can be grouped into a few sections.
+
+### Project management
+
+These commands are intended for managing development of a Python project. In these workflows, management of the virtual environment is done automatically by uv.
+
+- `uv add`
+- `uv remove`
+- `uv sync`
+- `uv lock`
+
+See the documentation on [projects](./preview/projects.md) for more details on getting started.
+
+### Toolchain management
+
+These commands are used to manage Python itself. uv is capable of installing and managing multiple Python versions.
+
+- `uv toolchain install`
+- `uv toolchain list`
+- `uv toolchain find`
+
+See the documentation on [toolchains](./preview/toolchains.md) for more details on getting started.
+
+### Command-line tool management
+
+These commands are used to manage command-line tools written in Python.
+
+- `uv tool run`
+
+See the documentation on [tools](./preview/tools.md) for more details on getting started.
+
+### Low-level plumbing commands
+
+The commands in this group allow manual management of environments and packages. They are intended to be used in legacy workflows or cases where the high-level commands do not provide enough control.
+
+This command is designed as replacement for the Python `venv` and `virtualenv` modules:
+
+- `uv venv`
+
+These commands are designed as replacements for `pip`:
+
+- `uv pip install`
+- `uv pip show`
+- `uv pip freeze`
+- `uv pip check`
+- `uv pip list`
+- `uv pip uninstall`
+
+These commands are designed as replacements for `pip-tools`:
+
+- `uv pip compile`
+- `uv pip sync`
+
+This command is designed as a replacement for `pipdeptree`:
+
+- `uv pip tree`
+
+Please note these commands do not exactly implement the interfaces and behavior of the tools that informed their design. Consult the [pip-compatibility guide](./pip/compatibility.md) for details on differences.