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">

docs/SUMMARY.md

@@ -7,17 +7,20 @@
 - [Installing uv](installation.md)
 - [First steps](first-steps.md)
 
-# Basic concepts
+# Guides
 
-- [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)
+- [Installing Python](guides/install-python.md)
+- [Running scripts](guides/scripts.md)
+- [Installing tools](guides/tools.md)
+- [Creating a project](guides/projects.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)
 - [Caching](cache.md)
 - [Authentication](configuration/authentication.md)
@@ -33,14 +36,13 @@
 - [Using in GitHub Actions](guides/github.md)
 - [Using in pre-commit](guides/pre-commit.md)
 
-# Preview features
+# Low-level operations
 
-- [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)
+- [Using environments](pip/environments.md)
+- [Managing packages](pip/packages.md)
+- [Inspecting packages](pip/inspection.md)
+- [Declaring dependencies](pip/dependencies.md)
+- [Locking environments](pip/compile.md)
 
 # Policies
 

docs/guides/install-python.md

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

docs/guides/project.md

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

docs/guides/projects.md

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

docs/guides/scripts.md

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

docs/guides/tools.md

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

docs/pip/environments.md

@@ -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
 interpreter's environment. Invoking uv via Python adds startup overhead and is not recommended for
 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.

docs/preview/toolchains.md

@@ -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.
 
 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.

docs/python/discovery.md

@@ -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.

docs/style.css

@@ -12,15 +12,17 @@ html {
 }
 .chapter li.chapter-item {
     margin-left: 1em;
-    margin-block-start: 0.3em;
+    margin-block-start: 0.2em;
     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 {
     text-decoration: underline;
 }
 .chapter li.part-title {
-    margin: 10px 0 0px 0;
+    margin: 0 0 0 0;
     font-weight: 500;
     font-size: 1.3em;
 }