Misc. improvements to the documentation (#11255)

README.md

@@ -26,17 +26,17 @@ An extremely fast Python package and project manager, written in Rust.
 - 🚀 A single tool to replace `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `twine`, `virtualenv`,
   and more.
 - ⚡️ [10-100x faster](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md) than `pip`.
-- 🐍 [Installs and manages](#python-management) Python versions.
+- 🗂️ Provides [comprehensive project management](#project), with a
-- 🛠️ [Runs and installs](#tool-management) Python applications.
+  [universal lockfile](https://docs.astral.sh/uv/concepts/projects/layout.md#the-lockfile).
-- ❇️ [Runs single-file scripts](#script-support), with support for
+- ❇️ [Runs scripts](#script-support), with support for
-  [inline dependency metadata](https://docs.astral.sh/uv/guides/scripts#declaring-script-dependencies).
+  [inline dependency metadata](https://docs.astral.sh/uv/guides/scripts.md#declaring-script-dependencies).
-- 🗂️ Provides [comprehensive project management](#project-management), with a
+- 🐍 [Installs and manages](#python-versions) Python versions.
-  [universal lockfile](https://docs.astral.sh/uv/concepts/projects#project-lockfile).
+- 🛠️ [Runs and installs](#tool) tools published as Python packages.
-- 🔩 Includes a [pip-compatible interface](#a-pip-compatible-interface) for a performance boost with
+- 🔩 Includes a [pip-compatible interface](#the-pip-interface) for a performance boost with a
-  a familiar CLI.
+  familiar CLI.
-- 🏢 Supports Cargo-style [workspaces](https://docs.astral.sh/uv/concepts/workspaces) for scalable
+- 🏢 Supports Cargo-style [workspaces](https://docs.astral.sh/uv/concepts/projects/workspaces.md)
-  projects.
+  for scalable projects.
-- 💾 Disk-space efficient, with a [global cache](https://docs.astral.sh/uv/concepts/cache) for
+- 💾 Disk-space efficient, with a [global cache](https://docs.astral.sh/uv/concepts/cache.md) for
   dependency deduplication.
 - ⏬ Installable without Rust or Python via `curl` or `pip`.
 - 🖥️ Supports macOS, Linux, and Windows.
@@ -87,7 +87,7 @@ Additionally, the command line reference documentation can be viewed with `uv he
 
 ## Features
 
-### Project management
+### Projects
 
 uv manages project dependencies and environments, with support for lockfiles, workspaces, and more,
 similar to `rye` or `poetry`:
@@ -109,6 +109,13 @@ Installed 2 packages in 1ms
 
 $ uv run ruff check
 All checks passed!
+
+$ uv lock
+Resolved 2 packages in 0.33ms
+
+$ uv sync
+Resolved 2 packages in 0.70ms
+Audited 1 package in 0.02ms
 ```
 
 See the [project documentation](https://docs.astral.sh/uv/guides/projects/) to get started.
@@ -116,7 +123,31 @@ See the [project documentation](https://docs.astral.sh/uv/guides/projects/) to g
 uv also supports building and publishing projects, even if they're not managed with uv. See the
 [publish guide](https://docs.astral.sh/uv/guides/publish/) to learn more.
 
-### Tool management
+### Scripts
+
+uv manages dependencies and environments for single-file scripts.
+
+Create a new script and add inline metadata declaring its dependencies:
+
+```console
+$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py
+
+$ uv add --script example.py requests
+Updated `example.py`
+```
+
+Then, run the script in an isolated virtual environment:
+
+```console
+$ uv run example.py
+Reading inline script metadata from: example.py
+Installed 5 packages in 12ms
+<Response [200]>
+```
+
+See the [scripts documentation](https://docs.astral.sh/uv/guides/scripts/) to get started.
+
+### Tools
 
 uv executes and installs command-line tools provided by Python packages, similar to `pipx`.
 
@@ -154,7 +185,7 @@ ruff 0.5.0
 
 See the [tools documentation](https://docs.astral.sh/uv/guides/tools/) to get started.
 
-### Python management
+### Python versions
 
 uv installs Python and allows quickly switching between versions.
 
@@ -196,30 +227,6 @@ Pinned `.python-version` to `3.11`
 See the [Python installation documentation](https://docs.astral.sh/uv/guides/install-python/) to get
 started.
 
-### Script support
-
-uv manages dependencies and environments for single-file scripts.
-
-Create a new script and add inline metadata declaring its dependencies:
-
-```console
-$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py
-
-$ uv add --script example.py requests
-Updated `example.py`
-```
-
-Then, run the script in an isolated virtual environment:
-
-```console
-$ uv run example.py
-Reading inline script metadata from: example.py
-Installed 5 packages in 12ms
-<Response [200]>
-```
-
-See the [scripts documentation](https://docs.astral.sh/uv/guides/scripts/) to get started.
-
 ### A pip-compatible interface
 
 uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands.

docs/getting-started/features.md

@@ -3,7 +3,7 @@
 uv provides essential features for Python development — from installing Python and hacking on simple
 scripts to working on large projects that support multiple Python versions and platforms.
 
-uv's interface can be broken down into sections, which can be used independently or together.
+uv's interface can be broken down into sections, which are usable independently or together.
 
 ## Python versions
 

docs/guides/index.md

@@ -6,6 +6,7 @@ Check out one of the core guides to get started:
 - [Running scripts and declaring dependencies](./scripts.md)
 - [Running and installing applications as tools](./tools.md)
 - [Creating and working on projects](./projects.md)
+- [Building and publishing packages](./package.md)
 - [Integrate uv with other software, e.g., Docker, GitHub, PyTorch, and more](./integration/index.md)
 
 Or, explore the [concept documentation](../concepts/index.md) for comprehensive breakdown of each

docs/guides/integration/alternative-indexes.md

@@ -162,7 +162,7 @@ export UV_EXTRA_INDEX_URL="https://aws:${AWS_CODEARTIFACT_TOKEN}@${AWS_DOMAIN}-$
 ### Publishing packages
 
 If you also want to publish your own packages to AWS CodeArtifact, you can use `uv publish` as
-described in the [publishing guide](../publish.md). You will need to set `UV_PUBLISH_URL` separately
+described in the [publishing guide](../package.md). You will need to set `UV_PUBLISH_URL` separately
 from the credentials:
 
 ```bash

docs/guides/package.md

@@ -1,9 +1,9 @@
 ---
-title: Publishing a package
+title: Building and publishing a package
 description: A guide to using uv to build and publish Python packages to a package index, like PyPI.
 ---
 
-# Publishing a package
+# Building and publishing a package
 
 uv supports building Python packages into source and binary distributions via `uv build` and
 uploading them to a registry with `uv publish`.

docs/guides/projects.md

@@ -232,4 +232,4 @@ To learn more about working on projects with uv, see the
 [projects concept](../concepts/projects/index.md) page and the
 [command reference](../reference/cli.md#uv).
 
-Or, read on to learn how to [publish your project as a package](./publish.md).
+Or, read on to learn how to [build and publish your project to a package index](./package.md).

docs/index.md

@@ -19,12 +19,12 @@ An extremely fast Python package and project manager, written in Rust.
 - 🚀 A single tool to replace `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `twine`, `virtualenv`,
   and more.
 - ⚡️ [10-100x faster](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md) than `pip`.
-- 🐍 [Installs and manages](#python-management) Python versions.
+- 🗂️ Provides [comprehensive project management](#project), with a
-- 🛠️ [Runs and installs](#tool-management) Python applications.
+  [universal lockfile](./concepts/projects/layout.md#the-lockfile).
 - ❇️ [Runs scripts](#script-support), with support for
   [inline dependency metadata](./guides/scripts.md#declaring-script-dependencies).
-- 🗂️ Provides [comprehensive project management](#project-management), with a
+- 🐍 [Installs and manages](#python-versions) Python versions.
-  [universal lockfile](./concepts/projects/layout.md#the-lockfile).
+- 🛠️ [Runs and installs](#tool) tools published as Python packages.
 - 🔩 Includes a [pip-compatible interface](#the-pip-interface) for a performance boost with a
   familiar CLI.
 - 🏢 Supports Cargo-style [workspaces](./concepts/projects/workspaces.md) for scalable projects.
@@ -35,7 +35,7 @@ An extremely fast Python package and project manager, written in Rust.
 uv is backed by [Astral](https://astral.sh), the creators of
 [Ruff](https://github.com/astral-sh/ruff).
 
-## Getting started
+## Installation
 
 Install uv with our official standalone installer:
 
@@ -58,7 +58,7 @@ Then, check out the [first steps](./getting-started/first-steps.md) or read on f
     uv may also be installed with pip, Homebrew, and more. See all of the methods on the
     [installation page](./getting-started/installation.md).
 
-## Project management
+## Projects
 
 uv manages project dependencies and environments, with support for lockfiles, workspaces, and more,
 similar to `rye` or `poetry`:
@@ -80,14 +80,45 @@ Installed 2 packages in 1ms
 
 $ uv run ruff check
 All checks passed!
+
+$ uv lock
+Resolved 2 packages in 0.33ms
+
+$ uv sync
+Resolved 2 packages in 0.70ms
+Audited 1 package in 0.02ms
 ```
 
 See the [project guide](./guides/projects.md) to get started.
 
 uv also supports building and publishing projects, even if they're not managed with uv. See the
-[publish guide](./guides/publish.md) to learn more.
+[packaging guide](./guides/package.md) to learn more.
 
-## Tool management
+## Scripts
+
+uv manages dependencies and environments for single-file scripts.
+
+Create a new script and add inline metadata declaring its dependencies:
+
+```console
+$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py
+
+$ uv add --script example.py requests
+Updated `example.py`
+```
+
+Then, run the script in an isolated virtual environment:
+
+```console
+$ uv run example.py
+Reading inline script metadata from: example.py
+Installed 5 packages in 12ms
+<Response [200]>
+```
+
+See the [scripts guide](./guides/scripts.md) to get started.
+
+## Tools
 
 uv executes and installs command-line tools provided by Python packages, similar to `pipx`.
 
@@ -125,7 +156,7 @@ ruff 0.5.4
 
 See the [tools guide](./guides/tools.md) to get started.
 
-## Python management
+## Python versions
 
 uv installs Python and allows quickly switching between versions.
 
@@ -166,30 +197,6 @@ Pinned `.python-version` to `3.11`
 
 See the [installing Python guide](./guides/install-python.md) to get started.
 
-## Script support
-
-uv manages dependencies and environments for single-file scripts.
-
-Create a new script and add inline metadata declaring its dependencies:
-
-```console
-$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py
-
-$ uv add --script example.py requests
-Updated `example.py`
-```
-
-Then, run the script in an isolated virtual environment:
-
-```console
-$ uv run example.py
-Reading inline script metadata from: example.py
-Installed 5 packages in 12ms
-<Response [200]>
-```
-
-See the [scripts guide](./guides/scripts.md) to get started.
-
 ## The pip interface
 
 uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands.

mkdocs.template.yml

@@ -68,6 +68,7 @@ plugins:
       # Note that redirecting an anchor, e.g., `concepts/projects/#managing-dependencies` must be done
       # client-side and is implemented in `extra.js` instead.
       redirect_maps:
+        "guides/publish.md": "guides/package.md"
         "concepts/workspaces.md": "concepts/projects/workspaces.md"
         "concepts/dependencies.md": "concepts/projects/dependencies.md"
         "reference/versioning.md": "reference/policies/versioning.md"
@@ -103,7 +104,7 @@ nav:
       - Running scripts: guides/scripts.md
       - Using tools: guides/tools.md
       - Working on projects: guides/projects.md
-      - Publishing packages: guides/publish.md
+      - Publishing packages: guides/package.md
       - Integrations:
           - guides/integration/index.md
           - Docker: guides/integration/docker.md
@@ -166,4 +167,3 @@ validation:
   omitted_files: warn
   absolute_links: warn
   unrecognized_links: warn
-  anchors: warn