Bundle of docs changes (#5426)

docs/features.md

@@ -3,101 +3,94 @@
 
 uv supports the full Python development experience — from installing Python and hacking on simple scripts to working on large projects that support multiple Python versions and platforms.
 
-uv's commands can be broken down into sections of discrete features which can be used independently.
+uv's commands can be broken down into sections of discrete features, which can be used independently.
 
-## Python version management
+## Python versions
 
 Installing and managing Python itself.
 
-- `uv python install`
+- `uv python install`: Install Python versions.
-- `uv python list`
+- `uv python list`: View available Python versions.
-- `uv python find`
+- `uv python find`: Find an installed Python version.
-- `uv python pin`
+- `uv python pin`: Pin the current project to use a specific Python version.
-- `uv python uninstall`
+- `uv python uninstall`: Uninstall a Python version.
 
 See the [guide on installing Python](./guides/install-python.md) to get started.
 
-## Running scripts
+## Scripts
 
 Executing standalone Python scripts, e.g., `example.py`.
 
-- `uv run`
+- `uv run`: Run a script.
 
 See the [guide on running scripts](./guides/scripts.md) to get started.
 
-## Project management
+## Projects
 
 Creating and working on Python projects, i.e., with a `pyproject.toml`.
 
-- `uv init`
+- `uv init`: Create a new Python project.
-- `uv add`
+- `uv add`: Add a dependency to the project.
-- `uv remove`
+- `uv remove`: Remove a dependency from the project.
-- `uv sync`
+- `uv sync`: Sync the project's dependencies with the environment.
-- `uv lock`
+- `uv lock`: Create a lockfile for the project's dependencies.
-- `uv run`
+- `uv run`: Run a command in the project environment.
-- `uv tree`
+- `uv tree`: View the dependency tree for the project.
 
 See the [guide on projects](./guides/projects.md) to get started.
 
-## Tool installation
+## Tools
 
 Running and installing tools published to Python package indexes, e.g., `ruff` or `black`.
 
-- `uvx` / `uv tool run`
+- `uvx` / `uv tool run`: Run a tool in a temporary environment.
-- `uv tool install`
+- `uv tool install`: Install a tool user-wide.
-- `uv tool uninstall`
+- `uv tool uninstall`: Uninstall a tool.
-- `uv tool list`
+- `uv tool list`: List installed tools.
-- `uv tool update-shell`
+- `uv tool update-shell`: Update the shell to include tool executables.
 
 See the [guide on tools](./guides/tools.md) to get started.
 
-## Low-level commands
+## Low-level
 
 Manually managing environments and packages — intended to be used in legacy workflows or cases where the high-level commands do not provide enough control.
 
 Creating virtual environments (replacing `venv` and `virtualenv`):
 
-- `uv venv`
+- `uv venv`: Create a new virtual environment.
 
 See the documentation on [using environments](./pip/environments.md) for details.
 
-Managing packages in an environment (replacing [`pip`](https://github.com/pypa/pip)):
+Managing packages in an environment (replacing [`pip`](https://github.com/pypa/pip) and [`pipdeptree`](https://github.com/tox-dev/pipdeptree)):
 
-- `uv pip install`
+- `uv pip install`: Install packages into the current environment.
-- `uv pip show`
+- `uv pip show`: Show details about an installed package.
-- `uv pip freeze`
+- `uv pip freeze`: List installed packages and their versions.
-- `uv pip check`
+- `uv pip check`: Check that the current environment has compatible packages.
-- `uv pip list`
+- `uv pip list`: List installed packages.
-- `uv pip uninstall`
+- `uv pip uninstall`: Uninstall packages.
+- `uv pip tree`: View the dependency tree for the environment.
 
 See the documentation on [managing packages](./pip/packages.md) for details.
 
 Locking packages in an environment (replacing [`pip-tools`](https://github.com/jazzband/pip-tools)):
 
-- `uv pip compile`
+- `uv pip compile`: Compile requirements into a lockfile.
-- `uv pip sync`
+- `uv pip sync`: Sync an environment with a lockfile.
 
 See the documentation on [locking environments](./pip/compile.md) for details.
 
-Viewing package dependencies in an environment (replacing [`pipdeptree`](https://github.com/tox-dev/pipdeptree)):
-
-- `uv pip tree`
-
 !!! important
 
     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](./pip/compatibility.md) for details.
 
-## Internal commands
+## Internal
 
 Managing and inspecting uv's state, such as the cache, storage directories, or performing a self-update:
 
-- `uv cache clean`
+- `uv cache clean`: Remove cache entries.
-- `uv cache prune`
+- `uv cache prune`: Remove outdated cache entries.
-- `uv cache dir`
+- `uv cache dir`: Show the uv cache directory path.
-- `uv tool dir`
+- `uv tool dir`: Show the uv tool directory path.
-- `uv python dir`
+- `uv python dir`: Show the uv installed Python versions path.
-- `uv self update`
+- `uv self update`: Update uv to the latest version.
-
-## Next steps
-
-Check out the [documentation overview](./overview.md) for a list of guides and concepts.

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 the [feature overview](./features.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/overview.md) to start using uv.

docs/guides/install-python.md

@@ -2,6 +2,10 @@
 
 If Python is already installed on your system, uv will [detect and use](#using-an-existing-python-installation) it without configuration. However, uv can also install and manage Python versions for you.
 
+!!! tip
+
+    uv will [automatically fetch Python versions](#automatic-python-downloads) as needed — you don't need to install Python to get started.
+
 To install the latest Python version:
 
 ```console
@@ -59,10 +63,10 @@ Note that Python does not need to be explicitly installed to use uv. By default,
 $ uv run --python 3.12 python -c 'print("hello world")'
 ```
 
-Even if a specific Python version is not requested, uv will download the latest version on demand. For example, the following will create a new virtual environment and download a managed Python version if one hasn't been installed yet:
+Even if a specific Python version is not requested, uv will download the latest version on demand. For example, the following will create a new virtual environment and download a managed Python version if Python is not found:
 
 ```console
-$ uv venv --python-preference only-managed
+$ uv venv
 ```
 
 <!-- TODO(zanieb): Restore when Python shim management is added

docs/guides/overview.md

@@ -0,0 +1,26 @@
+# Overview
+
+Check out one of the core guides to get started: 
+
+- [Installing Python versions](./install-python.md)
+- [Running scripts and declaring dependencies](./scripts.md) 
+- [Running and installing applications as tools](./tools.md) 
+- [Creating and working on projects](./projects.md) 
+
+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)
+
+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)

docs/guides/projects.md

@@ -1,6 +1,6 @@
 # Working on projects
 
-uv is capable of managing Python projects following the `pyproject.toml` standard.
+uv is capable of managing Python projects using a `pyproject.toml` with a `[project]` metadata table.
 
 ## Creating a new project
 
@@ -69,6 +69,10 @@ such as it's description or license. You can edit this file manually, or use
 commands like `uv add` and `uv remove` to manage your project through the
 CLI.
 
+!!! tip
+
+    See the official [`pyproject.toml` guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) for more details on getting started with the `pyproject.toml` format.
+
 ### `.venv`
 
 The `.venv` folder contains your project's virtual environment, a Python
@@ -102,9 +106,14 @@ virtual environment before executing a command:
 
 ```console
 $ uv sync
+$ source .venv/bin/active
 $ python my_script.py
 ```
 
+!!! note
+
+    The virtual environment must be active to run scripts and commands in the project without `uv run`. Virtual environment activation differs per shell and platform.
+
 ## Managing dependencies
 
 You can add dependencies to your `pyproject.toml` with the `uv add` command.

docs/guides/scripts.md

@@ -102,7 +102,7 @@ Note that if `uv run` is used in a _project_, these dependencies will be include
 
 Python recently added a standard format for [inline script metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/#inline-script-metadata). This allows the dependencies for a script to be declared in the script itself.
 
-To use inline script metadata, include a `script` section at the top of the script:
+To use inline script metadata, include a `script` section at the top of the script and declare the dependencies using TOML:
 
 ```python title="example.py"
 # /// script

docs/guides/tools.md

@@ -1,6 +1,6 @@
 # Using tools
 
-Many Python packages provide command-line interfaces which are useful as standalone tools. uv has specialized support for easily invoking and installing tools.
+Many Python packages provide applications that can be used as tools. uv has specialized support for easily invoking and installing tools.
 
 ## Using `uvx`
 
@@ -90,7 +90,7 @@ $ uvx --with mkdocs-material mkdocs --help
 
 ## Installing tools
 
-If a tool is used often, it can be useful to install it to a persistent environment instead of invoking `uvx` repeatedly.
+If a tool is used often, it can be useful to install it to a persistent environment and add it to the `PATH` instead of invoking `uvx` repeatedly.
 
 To install `ruff`:
 

docs/index.md

@@ -23,30 +23,30 @@ An extremely fast Python package and project manager, written in Rust.
 ## Highlights
 
 - 🐍 [Installs and manages](./guides/install-python.md) Python versions.
-- 🛠️ [Executes and installs](./guides/tools.md) commands provided by Python packages.
+- 🛠️ [Runs and installs](./guides/tools.md) Python applications.
-- ❇️ [Runs scripts](./guides/scripts.md) with [inline dependency metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/#inline-script-metadata).
+- ❇️ [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 multi-platform lock file.
+- 🗂️ Provides [comprehensive project management](./guides/projects.md), with a [universal lockfile](./projects.md#lock-file).
-- 🏢 Supports Cargo-style [workspaces](./workspaces.md) for large projects.
+- 🏢 Supports Cargo-style [workspaces](./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`).
-- 🧪 Tested at-scale against the top 10,000 PyPI packages.
 - 💾 Disk-space efficient, with a [global cache](./cache.md) for dependency deduplication.
-- ⁉️ Best-in-class error messages with a conflict-tracking resolver.
+- ⏬ Installable without Rust or Python via `curl` or `pip`.
-- ⏬ A static binary that can be installed without Rust or Python via `curl` or `pip`.
+- 🖥️ Supports macOS, Linux, and Windows.
-- 🖥️ Support for macOS, Linux, and Windows.
 
 uv is backed by [Astral](https://astral.sh), the creators of [Ruff](https://github.com/astral-sh/ruff).
 
 ## Getting started
 
-Install uv with our official standalone installer:
+Install uv with our official standalone installer, on macOS and Linux:
 
 ```bash
-# On macOS and Linux.
 curl -LsSf https://astral.sh/uv/install.sh | sh
+```
 
-# On Windows.
+Or, on Windows:
+
+```bash
 powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 
@@ -54,7 +54,7 @@ Then, check out the [first steps](./first-steps.md), see more [installation meth
 
 ## Project management
 
-uv can manage project dependencies and environments:
+uv manages project dependencies and environments:
 
 ```console
 $ uv init example
@@ -71,7 +71,7 @@ Installed 2 packages in 1ms
  + example==0.1.0 (from file:///home/user/example)
  + ruff==0.5.4
 
-$ uv run -- ruff check
+$ uv run ruff check
 All checks passed!
 ```
 
@@ -79,7 +79,7 @@ See the [project guide](./guides/projects.md) to get started.
 
 ## Tool management
 
-uv provides an interface for executing and installing command-line tools provided by Python packages, similar to `pipx`. 
+uv executes and installs command-line tools provided by Python packages, similar to `pipx`. 
 
 Run a tool in an ephemeral environment with `uvx`:
 
@@ -117,7 +117,7 @@ See the [tools guide](./guides/tools.md) to get started.
 
 ## Python management
 
-uv supports installing Python and managing multiple Python versions.
+uv installs Python and allows quickly switching between Python versions.
 
 Install the Python versions your project requires:
 
@@ -137,8 +137,22 @@ Or, fetch Python versions on demand:
 
 ```console
 $ uv venv --python 3.12.0
+Using Python 3.12.0
 Creating virtualenv at: .venv
 Activate with: source .venv/bin/activate
+
+$ uv run --python pypy@3.8 -- python --version
+Python 3.8.16 (a9dbdca6fc3286b0addd2240f11d97d8e8de187a, Dec 29 2022, 11:45:30)
+[PyPy 7.3.11 with GCC Apple LLVM 13.1.6 (clang-1316.0.21.2.5)] on darwin
+Type "help", "copyright", "credits" or "license" for more information.
+>>>> 
+```
+
+Use a specific Python version in the current directory:
+
+```
+$ uv python pin pypy@3.11
+Pinned `.python-version` to `pypy@3.11`
 ```
 
 See the [installing Python guide](./guides/install-python.md) to get started.
@@ -161,7 +175,7 @@ Create a virtual environment:
 
 ```console
 $ uv venv
-Using Python 3.12.3 interpreter at: /opt/homebrew/opt/python@3.12/bin/python3.12
+Using Python 3.12.3
 Creating virtualenv at: .venv
 Activate with: source .venv/bin/activate
 ```
@@ -182,4 +196,4 @@ See the [uv pip documentation](./pip/environments.md) to get started.
 
 ## Next steps
 
-See the [documentation overview](./overview.md) to learn more about uv.
+See the [first steps](./first-steps.md) or jump straight into the [guides](./guides/overview.md) to start using uv.

docs/installation.md

@@ -16,7 +16,7 @@ powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 
 uv is installed to `~/.cargo/bin`.
 
-!!! note
+!!! tip
 
     The installation script may be inspected with:
 
@@ -40,13 +40,13 @@ curl -LsSf https://astral.sh/uv/0.2.11/install.sh | sh
 powershell -c "irm https://astral.sh/uv/0.2.11/install.ps1 | iex"
 ```
 
-When the standalone installer is used, uv can upgrade itself.
+When the standalone installer is used, uv can upgrade itself:
 
 ```bash
 uv self update
 ```
 
-When all other installers are used, self updates are disabled. Use the package manager's upgrade method instead.
+When another installation method is used, self updates are disabled. Use the package manager's upgrade method instead.
 
 ## PyPI
 

docs/overview.md

@@ -1,23 +0,0 @@
-# Overview
-
-Check out one of our guides to get started: 
-
-- [Installing Python](./guides/install-python.md) 
-- [Running scripts](./guides/scripts.md) 
-- [Using tools](./guides/tools.md) 
-- [Working on projects](./guides/projects.md) 
-- [Using in Docker](./guides/integration/docker.md)
-- [Using with pre-commit](./guides/integration/pre-commit.md)
-- [Using in GitHub Actions](./guides/integration/github.md)
-- [Using with commercial package indexes](./guides/integration/commercial-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)

docs/projects.md

@@ -2,7 +2,7 @@
 
 Python projects are help manage Python applications spanning multiple files.
 
-!!! note
+!!! tip
 
     Looking for an introduction to creating a project with uv? See the [projects guide](./guides/projects.md) first.
 
@@ -32,6 +32,8 @@ This Python version requirement determines what syntax is valid in the project a
 
 The `pyproject.toml` also lists dependencies of the project. uv supports modifying the standard dependency list from the command line with `uv add` and `uv remove`. uv also supports [extended package sources](./dependencies.md) for advanced users.
 
+!!! tip
+
     See the official [`pyproject.toml` guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) for more details on getting started with a `pyproject.toml`.
 
 ## Project environments

mkdocs.template.yml

@@ -74,8 +74,8 @@ nav:
       - Installation: installation.md
       - First steps: first-steps.md
       - Features: features.md
-      - Overview: overview.md
   - Guides:
+      - Overview: guides/overview.md
       - Installing Python: guides/install-python.md
       - Running scripts: guides/scripts.md
       - Using tools: guides/tools.md