Bundle of documentation changes

docs/concepts/index.md

@@ -0,0 +1,13 @@
+# Concepts overview
+
+Read the concept documents to learn more about uv's features:
+
+- [Projects](./projects.md)
+- [Dependencies](./dependencies.md)
+- [Workspaces](./workspaces.md)
+- [Tools](./tools.md)
+- [Python versions](./python-versions.md)
+- [Resolution](./resolution.md)
+- [Caching](./cache.md)
+
+Looking for a quick introduction to features? See the [guides](../guides/index.md) instead.

docs/projects.md → docs/concepts/projects.md

@@ -4,7 +4,7 @@ Python projects are help manage Python applications spanning multiple files.
 
 !!! tip
 
-    Looking for an introduction to creating a project with uv? See the [projects guide](./guides/projects.md) first.
+    Looking for an introduction to creating a project with uv? See the [projects guide](../guides/projects.md) first.
 
 ## Project metadata
 
@@ -44,7 +44,7 @@ To run a command in the project environment, use `uv run`. Alternatively the pro
 
 When `uv run` is invoked, it will create the project environment if it does not exist yet or ensure it is up to date if it exists. The project environment can also be explicitly created with `uv sync`.
 
-It is _not_ recommended to modify the project environment manually, e.g., with `uv pip install`. For project dependencies, use `uv add` to add a package to the environment. For one-off requirements, use [`uvx`](./guides/tools.md) or [`uv run --with`](#running-commands-with-additional-dependencies).
+It is _not_ recommended to modify the project environment manually, e.g., with `uv pip install`. For project dependencies, use `uv add` to add a package to the environment. For one-off requirements, use [`uvx`](../guides/tools.md) or [`uv run --with`](#running-commands-with-additional-dependencies).
 
 ## Lock file
 
@@ -150,7 +150,7 @@ The requested version will be respected regardless of the project's requirements
 
 ### Running scripts
 
-Scripts that declare inline metadata are automatically executed in environments isolated from the project. See the [scripts guide](./guides/scripts.md#declaring-script-dependencies) for more details.
+Scripts that declare inline metadata are automatically executed in environments isolated from the project. See the [scripts guide](../guides/scripts.md#declaring-script-dependencies) for more details.
 
 For example, given a script:
 

docs/resolution.md → docs/concepts/resolution.md

@@ -80,7 +80,7 @@ to model, and are a frequent source of bugs in other packaging tools. uv's pre-r
 is _intentionally_ limited and _intentionally_ requires user opt-in for pre-releases, to ensure
 correctness.
 
-For more, see ["Pre-release compatibility"](./pip/compatibility.md#pre-release-compatibility)
+For more, see ["Pre-release compatibility"](../pip/compatibility.md#pre-release-compatibility)
 
 ## Dependency overrides
 
@@ -116,7 +116,7 @@ architectures, and Python implementations. In universal mode, the current Python
 will be treated as a lower bound. For example, `--universal --python-version 3.7` would produce a universal resolution 
 for Python 3.7 and later.
 
-If using uv's [project](./guides/projects.md) interface, the machine agnostic resolution will be used
+If using uv's [project](../guides/projects.md) interface, the machine agnostic resolution will be used
 automatically and a `uv.lock` file will be created. The lock file can also be created with an explicit `uv lock`
 invocation.
 

docs/tools.md → docs/concepts/tools.md

@@ -4,7 +4,7 @@ Tools are Python packages that provide command-line interfaces. Tools can be inv
 
 !!! note
 
-    See the [tools guide](./guides/tools.md) for an introduction to working with the tools interface — this document discusses details of tool management.
+    See the [tools guide](../guides/tools.md) for an introduction to working with the tools interface — this document discusses details of tool management.
 
 ## Tool environments
 

docs/configuration/authentication.md

@@ -67,6 +67,6 @@ 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.
 
-## Authentication with commercial package indexes
+## Authentication with alternative package indexes
 
-See the [commercial indexes integration guide](../guides/integration/commercial-indexes.md) for details on authentication with popular commercial Python package indexes.
+See the [alternative indexes integration guide](../guides/integration/alternative-indexes.md) for details on authentication with popular alternative Python package indexes.

docs/configuration/index.md

@@ -0,0 +1,11 @@
+# Configuration overview
+
+Read about the various ways to configure uv:
+
+- [Using configuration files](./files.md)
+- [Using environment variables](./environment.md)
+- [Configuring authentication](./authentication.md)
+
+<!-- TODO(zanieb): Move generated settings reference to correct section -->
+
+Or, jump to the [settings reference](../settings.md) which enumerates the available configuration options.

docs/features.md

@@ -51,7 +51,7 @@ Running and installing tools published to Python package indexes, e.g., `ruff` o
 
 See the [guide on tools](./guides/tools.md) to get started.
 
-## Low-level
+## The pip interface
 
 Manually managing environments and packages — intended to be used in legacy workflows or cases where the high-level commands do not provide enough control.
 

docs/first-steps.md

@@ -56,4 +56,4 @@ When using the long help menu, uv will attempt to use `less` or `more` to "page"
 
 ## Next steps
 
-Now that you've confirmed uv is installed and know how to get help, check out an [overview of features](./features.md) or jump straight into the [guides](./guides/overview.md) to start using uv.
+Now that you've confirmed uv is installed and know how to get help, check out an [overview of features](./features.md) or jump straight into the [guides](./guides/index.md) to start using uv.

docs/guides/overview.md → docs/guides/index.md

@@ -1,4 +1,4 @@
-# Overview
+# Guides overview
 
 Check out one of the core guides to get started: 
 
@@ -12,15 +12,6 @@ Learn how to integrate uv with other software:
 - [Using in Docker images](./integration/docker.md)
 - [Using with pre-commit](./integration/pre-commit.md)
 - [Using in GitHub Actions](./integration/github.md)
-- [Using with commercial package indexes](./integration/commercial-indexes.md)
+- [Using with alternative package indexes](./integration/alternative-indexes.md)
 
-Or, explore the concept documentation for comprehensive breakdown of each feature:
-
-- [Projects](../projects.md)
-- [Dependencies](../dependencies.md)
-- [Workspaces](../workspaces.md)
-- [Tools](../tools.md)
-- [Python versions](../python-versions.md)
-- [Resolution](../resolution.md)
-- [Caching](../cache.md)
-- [Authentication](../configuration/authentication.md)
+Or, explore the [concept documentation](../concepts/index.md) for comprehensive breakdown of each feature.

docs/guides/install-python.md

@@ -16,7 +16,7 @@ This will install a uv managed Python version even if there is already a Python
 
 !!! note
 
-    Python does not publish official distributable binaries so uv uses third-party distributions from the [`python-build-standalone`](https://github.com/indygreg/python-build-standalone) project. The project is partially maintained by the uv maintainers and is used by many other Python projects. See the [Python distributions](../python-versions.md#python-distributions) documentation for more details.
+    Python does not publish official distributable binaries so uv uses third-party distributions from the [`python-build-standalone`](https://github.com/indygreg/python-build-standalone) project. The project is partially maintained by the uv maintainers and is used by many other Python projects. See the [Python distributions](../concepts/python-versions.md#python-distributions) documentation for more details.
 
 
 <!-- TODO(zanieb): Restore when Python shim management is added
@@ -41,7 +41,7 @@ To install a specific Python version:
 $ uv python install 3.12
 ```
 
-See the [`python install`](../python-versions.md#installing-a-python-version) documentation for more details.
+See the [`python install`](../concepts/python-versions.md#installing-a-python-version) documentation for more details.
 
 ## Viewing Python installations
 
@@ -51,7 +51,7 @@ To view available and installed Python versions:
 $ uv python list
 ```
 
-See the [`python list`](../python-versions.md#viewing-available-python-versions) documentation for more details.
+See the [`python list`](../concepts/python-versions.md#viewing-available-python-versions) documentation for more details.
 
 <!--TODO(zanieb): The above should probably link to a CLI reference and that content should be moved out of that file -->
 
@@ -75,6 +75,6 @@ Note that when an automatic Python installation occurs, the `python` command wil
 
 ## Using an existing Python installation
 
-uv will also use an existing Python installation if already present on your system. There is no configuration necessary for this behavior: uv will use the system Python if it satisfies the requirements of the command invocation. See the [Python discovery](../python-versions.md#discovery-order) documentation for details.
+uv will also use an existing Python installation if already present on your system. There is no configuration necessary for this behavior: uv will use the system Python if it satisfies the requirements of the command invocation. See the [Python discovery](../concepts/python-versions.md#discovery-order) documentation for details.
 
-To force uv to use the system Python, provide the `--python-preference only-system` option. See the [Python version preference](../python-versions.md#adjusting-python-version-preferences) documentation for more details.
+To force uv to use the system Python, provide the `--python-preference only-system` option. See the [Python version preference](../concepts/python-versions.md#adjusting-python-version-preferences) documentation for more details.

docs/guides/integration/commercial-indexes.md → docs/guides/integration/alternative-indexes.md

@@ -1,6 +1,6 @@
-# Using uv commercial package indexes
+# Using alternative package indexes
 
-While uv uses the official Python Package Index (PyPI) by default, it also supports commercial package indexes. Most commercial indexes require various forms of authentication, which requires some initial setup.
+While uv uses the official Python Package Index (PyPI) by default, it also supports alternative package indexes. Most alternative indexes require various forms of authentication, which requires some initial setup.
 
 ## Azure Artifacts
 

docs/guides/integration/index.md

@@ -0,0 +1,8 @@
+# Integration guides
+
+Learn how to integrate uv with other software:
+
+- [Using in Docker images](./docker.md)
+- [Using with pre-commit](./pre-commit.md)
+- [Using in GitHub Actions](./github.md)
+- [Using an Azure Artifacts index](./alternative-indexes.md#azure-artifacts)

docs/guides/projects.md

@@ -141,5 +141,5 @@ $ uv remove requests
 
 ## Next steps
 
-See the [projects concept](../projects.md) documentation for more details about
+See the [projects concept](../concepts/projects.md) documentation for more details about
 projects.

docs/guides/scripts.md

@@ -151,7 +151,7 @@ type Point = tuple[float, float]
 print(Point)
 ```
 
-uv will fetch the required Python version if it is not installed — see the documentation on [Python versions](../python-versions.md) for more details. Note that the `dependencies` field must be provided even if empty.
+uv will fetch the required Python version if it is not installed — see the documentation on [Python versions](../concepts/python-versions.md) for more details. Note that the `dependencies` field must be provided even if empty.
 
 Note that when using inline script metadata, even if `uv run` is used in a _project_, the project's dependencies will be ignored. The `--isolated` flag is not required.
 
@@ -177,4 +177,4 @@ $ uv run --python 3.10 example.py
 3.10.13
 ```
 
-See the [Python version request](../python-versions.md#requesting-a-version) documentation for more details on requesting Python versions.
+See the [Python version request](../concepts/python-versions.md#requesting-a-version) documentation for more details on requesting Python versions.

docs/guides/tools.md

@@ -142,4 +142,4 @@ $ uv tool install mkdocs --with mkdocs-material
 
 ## Next steps
 
-See the [tools concept](../tools.md) documentation for more details on how tools are managed.
+See the [tools concept](../concepts/tools.md) documentation for more details on how tools are managed.

docs/index.md

@@ -25,12 +25,12 @@ An extremely fast Python package and project manager, written in Rust.
 - 🐍 [Installs and manages](./guides/install-python.md) Python versions.
 - 🛠️ [Runs and installs](./guides/tools.md) Python applications.
 - ❇️ [Runs scripts](./guides/scripts.md), with support for [inline dependency metadata](./guides/scripts.md#declaring-script-dependencies).
-- 🗂️ Provides [comprehensive project management](./guides/projects.md), with a [universal lockfile](./projects.md#lock-file).
-- 🏢 Supports Cargo-style [workspaces](./workspaces.md) for scalable projects.
+- 🗂️ Provides [comprehensive project management](./guides/projects.md), with a [universal lockfile](./concepts/projects.md#lock-file).
+- 🏢 Supports Cargo-style [workspaces](./concepts/workspaces.md) for scalable projects.
 - 🚀 A replacement for `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `virtualenv`, and more.
 - ⚡️ [10-100x faster](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md) than `pip`
   and `pip-tools` (`pip-compile` and `pip-sync`).
-- 💾 Disk-space efficient, with a [global cache](./cache.md) for dependency deduplication.
+- 💾 Disk-space efficient, with a [global cache](./concepts/cache.md) for dependency deduplication.
 - ⏬ Installable without Rust or Python via `curl` or `pip`.
 - 🖥️ Supports macOS, Linux, and Windows.
 
@@ -157,7 +157,7 @@ Pinned `.python-version` to `pypy@3.11`
 
 See the [installing Python guide](./guides/install-python.md) to get started.
 
-## Package management
+## The pip interface
 
 uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands with support for
 a wide range of advanced `pip` features, including editable installs, Git dependencies, direct URL dependencies, local dependencies, constraints, source distributions, HTML and JSON indexes, and more.
@@ -192,8 +192,8 @@ Installed 43 packages in 208ms
  ...
 ```
 
-See the [uv pip documentation](./pip/environments.md) to get started.
+See the [uv pip documentation](./pip/index.md) to get started.
 
 ## Next steps
 
-See the [first steps](./first-steps.md) or jump straight into the [guides](./guides/overview.md) to start using uv.
+See the [first steps](./first-steps.md) or jump straight into the [guides](./guides/index.md) to start using uv.

docs/pip/environments.md

@@ -27,7 +27,7 @@ uv venv --python 3.11
 
 Note this requires the requested Python version to be available on the system.
 However, if available, uv will download Python for you.
-See the [Python version](../python-versions.md) documentation for more details.
+See the [Python version](../concepts/python-versions.md) documentation for more details.
 
 ## Using a virtual environment
 
@@ -115,4 +115,4 @@ If a specific Python version is requested, e.g., `--python 3.7`, additional exec
 
 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](../python-versions.md#discovery-order) for details on discovery.
+See the documentation on [toolchain discovery](../concepts/python-versions.md#discovery-order) for details on discovery.

docs/pip/index.md

@@ -0,0 +1,13 @@
+# The pip interface
+
+uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands. These commands work directly with the virtual environment, in contrast to uv's primary interfaces where the virtual environment is managed automatically. The `uv pip` interface exposes the speed and functionality of uv to power users and projects that are not ready to transition away from `pip` and `pip-tools`.
+
+The following sections discuss the basics of using `uv pip`:
+
+- [Creating and using environments](./environments.md)
+- [Installing and managing packages](./packages.md)
+- [Inspecting environments and packages](./inspection.md)
+- [Declaring package dependencies](./dependencies.md)
+- [Locking and syncing environments](./compile.md)
+
+Please note these commands do not _exactly_ implement the interfaces and behavior of the tools they are based on. The further you stray from common workflows, the more likely you are to encounter differences. Consult the [pip-compatibility guide](./compatibility.md) for details.

mkdocs.template.yml

@@ -8,6 +8,7 @@ theme:
     - navigation.instant.prefetch
     - navigation.instant.progress
     - navigation.expand
+    - navigation.indexes
     - navigation.tracking
     - content.code.annotate
     - toc.follow
@@ -75,30 +76,34 @@ nav:
       - First steps: first-steps.md
       - Features: features.md
   - Guides:
-      - Overview: guides/overview.md
+      - guides/index.md
       - Installing Python: guides/install-python.md
       - Running scripts: guides/scripts.md
       - Using tools: guides/tools.md
       - Working on projects: guides/projects.md
   - Concepts:
-      - Projects: projects.md
-      - Dependencies: dependencies.md
-      - Workspaces: workspaces.md
-      - Tools: tools.md
-      - Python versions: python-versions.md
-      - Resolution: resolution.md
-      - Caching: cache.md
-      - Authentication: configuration/authentication.md
+      - concepts/index.md
+      - Projects: concepts/projects.md
+      - Dependencies: concepts/dependencies.md
+      - Workspaces: concepts/workspaces.md
+      - Tools: concepts/tools.md
+      - Python versions: concepts/python-versions.md
+      - Resolution: concepts/resolution.md
+      - Caching: concepts/cache.md
   - Configuration:
+      - configuration/index.md
       - Configuration files: configuration/files.md
       - Environment variables: configuration/environment.md
       - Settings: settings.md
+      - Authentication: configuration/authentication.md
   - Integration guides:
+      - guides/integration/index.md
       - Docker: guides/integration/docker.md
       - GitHub Actions: guides/integration/github.md
       - Pre-commit: guides/integration/pre-commit.md
-      - Commercial indexes: guides/integration/commercial-indexes.md
-  - Low-level operations:
+      - Alternative indexes: guides/integration/alternative-indexes.md
+  - The pip interface:
+      - pip/index.md
       - Using environments: pip/environments.md
       - Managing packages: pip/packages.md
       - Inspecting packages: pip/inspection.md