From 9ba2bb7f96f81354ac9dc93aba603b9f5b07fb11 Mon Sep 17 00:00:00 2001
From: Charlie Marsh <charlie.r.marsh@gmail.com>
Date: Sun, 4 Aug 2024 21:37:16 -0400
Subject: [PATCH] Make some minor tweaks to the docs

---
 docs/concepts/dependencies.md     | 36 ++++++++++++++++++++++---------
 docs/first-steps.md               |  2 --
 docs/guides/install-python.md     |  2 +-
 docs/guides/integration/github.md |  4 ++--
 docs/guides/projects.md           | 10 ++++++---
 docs/guides/tools.md              |  2 +-
 docs/index.md                     | 16 ++++++++------
 docs/installation.md              | 13 +++++------
 8 files changed, 54 insertions(+), 31 deletions(-)

diff --git a/docs/concepts/dependencies.md b/docs/concepts/dependencies.md
index 1fe2668005a6..0481e8d0d272 100644
--- a/docs/concepts/dependencies.md
+++ b/docs/concepts/dependencies.md
@@ -1,13 +1,29 @@
 # Specifying dependencies
 
-In uv, project dependency specification is divided between two `pyproject.toml` tables:
-`project.dependencies` and `tool.uv.sources`.
+In uv, project dependencies are declared across two `pyproject.toml` tables: `project.dependencies`
+and `tool.uv.sources`.
 
-`project.dependencies` is used to define the standards-compliant dependency metadata, propagated
-when uploading to PyPI or building a wheel. `tool.uv.sources` is used to specify the _sources_
-required to install the dependencies, which can come from a Git repository, a URL, a local path, a
-different index, etc. This metadata must be expressed separately because the `project.dependencies`
-standard does not allow these common patterns.
+`project.dependencies` defines the standards-compliant dependency metadata, propagated when
+uploading to PyPI or building a wheel.
+
+`tool.uv.sources` enriches the dependency metadata with additional sources, incorporated during
+development. A dependency source can be a Git repository, a URL, a local path, or an alternative
+registry.
+
+`tool.uv.sources` enables uv to support common patterns like editable installations and relative
+paths that are not supported by the `project.dependencies` standard. For example:
+
+```toml title="pyproject.toml"
+[project]
+name = "albatross"
+version = "0.1.0"
+dependencies = [
+  "bird-feeder",
+]
+
+[tool.uv.sources]
+bird-feeder = { path = "/path/to/bird-feeder" }
+```
 
 ## Project dependencies
 
@@ -40,12 +56,12 @@ dependencies = [
 ```
 
 If the project only requires packages from standard package indexes, then `project.dependencies` is
-sufficient. If, the project depends on packages from Git, remote URLs, or local sources,
-`tool.uv.sources` is needed.
+sufficient. If the project depends on packages from Git, remote URLs, or local sources,
+`tool.uv.sources` can be used to enrich the dependency metadata.
 
 ## Dependency sources
 
-During development, the project may rely on a package that isn't available on PyPI. The following
+During development, a project may rely on a package that isn't available on PyPI. The following
 additional sources are supported by uv:
 
 - Git: A Git repository.
diff --git a/docs/first-steps.md b/docs/first-steps.md
index ef13bf4787f7..2a7cf696558e 100644
--- a/docs/first-steps.md
+++ b/docs/first-steps.md
@@ -1,7 +1,5 @@
 # First steps with uv
 
-uv only provides a command-line interface and must be used from a terminal.
-
 After [installing uv](./installation.md), you can check that uv is available by running the `uv`
 command:
 
diff --git a/docs/guides/install-python.md b/docs/guides/install-python.md
index 639cec2cb47c..2849722e0c75 100644
--- a/docs/guides/install-python.md
+++ b/docs/guides/install-python.md
@@ -23,7 +23,7 @@ system. If you've previously installed Python with uv, a new version will not be
 
 !!! 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](../concepts/python-versions.md#python-distributions) documentation for more details.
+    Python does not publish official distributable binaries. As such, 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 other prominent Python projects (e.g., [Rye](https://github.com/astral-sh/rye), [Bazel](https://github.com/bazelbuild/rules_python)). See the [Python distributions](../concepts/python-versions.md#python-distributions) documentation for more details.
 
 <!-- TODO(zanieb): Restore when Python shim management is added
 Note that when an automatic Python installation occurs, the `python` command will not be added to the shell. Use `uv python install-shim` to ensure the `python` shim is installed.
diff --git a/docs/guides/integration/github.md b/docs/guides/integration/github.md
index ddda491ed0f0..0bf3e15cc3f5 100644
--- a/docs/guides/integration/github.md
+++ b/docs/guides/integration/github.md
@@ -4,7 +4,7 @@
 
 uv installation differs depending on the platform.
 
-### on Unix
+### Unix
 
 ```yaml title="example.yml"
 name: Example on Unix
@@ -22,7 +22,7 @@ jobs:
         run: curl -LsSf https://astral.sh/uv/install.sh | sh
 ```
 
-### on Windows
+### Windows
 
 ```yaml title="example.yml"
 name: Example on Windows
diff --git a/docs/guides/projects.md b/docs/guides/projects.md
index 6422815ba1b5..3708b04d616e 100644
--- a/docs/guides/projects.md
+++ b/docs/guides/projects.md
@@ -27,7 +27,7 @@ This will create the following directory structure:
 ├── pyproject.toml
 ├── README.md
 └── src
-    └── hello-world
+    └── hello_world
         └── __init__.py
 ```
 
@@ -124,8 +124,12 @@ more details.
 
 ## Running commands
 
-`uv run` can be used to run arbitrary scripts or commands in your project environment. This ensures
-that the lockfile and project environment are up-to-date before executing a given command.
+`uv run` can be used to run arbitrary scripts or commands in your project environment.
+
+Prior to every `uv run` invocation, uv will verify that the lockfile is up-to-date with the
+`pyproject.toml`, and that the environment is up-to-date with the lockfile, keeping your project
+in-sync without the need for manual intervention. `uv run` guarantees that your command is run in a
+consistent, locked environment.
 
 For example, to use `flask`:
 
diff --git a/docs/guides/tools.md b/docs/guides/tools.md
index f187481436ed..a74bc7a2f1ac 100644
--- a/docs/guides/tools.md
+++ b/docs/guides/tools.md
@@ -21,7 +21,7 @@ $ uvx ruff
     $ uv tool run ruff
     ```
 
-    `uvx` is provided as a short alias since the operation is very common.
+    `uvx` is provided as an alias for convenience.
 
 Arguments can be provided after the tool name:
 
diff --git a/docs/index.md b/docs/index.md
index 85b15311cffd..7fe43d3c9ec9 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -16,6 +16,8 @@ An extremely fast Python package and project manager, written in Rust.
 
 ## Highlights
 
+- 🚀 A single tool to replace `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `virtualenv`, and more.
+- ⚡️ [10-100x faster](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md) than `pip`.
 - 🐍 [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
@@ -23,9 +25,6 @@ An extremely fast Python package and project manager, written in Rust.
 - 🗂️ Provides [comprehensive project management](./guides/projects.md), with a
   [universal lockfile](./concepts/projects.md#lockfile).
 - 🏢 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](./concepts/cache.md) for dependency deduplication.
 - ⏬ Installable without Rust or Python via `curl` or `pip`.
 - 🖥️ Supports macOS, Linux, and Windows.
@@ -54,7 +53,8 @@ Then, check out the [first steps](./first-steps.md) or read on for a brief overv
 
 ## Project management
 
-uv manages project dependencies and environments:
+uv manages project dependencies and environments, with support for lockfiles, workspaces, and more,
+similar to `rye` or `poetry`:
 
 ```console
 $ uv init example
@@ -158,11 +158,15 @@ See the [installing Python guide](./guides/install-python.md) to get started.
 
 ## The pip interface
 
-uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands. uv
-extends their interfaces with advanced features, such as dependency version overrides,
+uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands.
+
+uv extends their interfaces with advanced features, such as dependency version overrides,
 platform-independent resolutions, reproducible resolutions, alternative resolution strategies, and
 more.
 
+Migrate to uv without changing your existing workflows — and experience a 10-100x speedup — with the
+`uv pip` interface.
+
 Compile requirements into a platform-independent requirements file:
 
 ```console
diff --git a/docs/installation.md b/docs/installation.md
index 0459dfece4d4..d0a780c604d3 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -1,10 +1,11 @@
 # Installing uv
 
-Install uv with our standalone installers, from PyPI, or from your package manager of choice.
+Install uv with our standalone installers or your package manager of choice (e.g.,
+`pip install uv`).
 
 ## Standalone installer
 
-uv provides a standalone installer that downloads and installs uv:
+uv provides a standalone installer to downloads and install uv:
 
 ```console title="macOS and Linux"
 $ curl -LsSf https://astral.sh/uv/install.sh | sh
@@ -14,7 +15,7 @@ $ curl -LsSf https://astral.sh/uv/install.sh | sh
 $ powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 
-uv is installed to `~/.cargo/bin`.
+By default, uv is installed to `~/.cargo/bin`.
 
 !!! tip
 
@@ -42,7 +43,7 @@ $ powershell -c "irm https://astral.sh/uv/0.2.11/install.ps1 | iex"
 
 !!! tip
 
-    When the standalone installer is used, uv can perform self-updates:
+    When uv is installed via the standalone installer, self-updates are enabled:
 
     ```console
     $ uv self update
@@ -69,8 +70,8 @@ $ pip install uv
 
 !!! note
 
-    There are prebuilt distributions (wheels) for many platforms; if not available for a given
-    platform, uv will be built from source which requires a Rust toolchain to be installed. See the
+    uv ships with prebuilt distributions (wheels) for many platforms; if a wheel is not available for a given
+    platform, uv will be built from source, which requires a Rust toolchain. See the
     [contributing setup guide](https://github.com/astral-sh/uv/blob/main/CONTRIBUTING.md#setup)
     for details on building uv from source.