Misc. improvements to the documentation (#11255)

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.
-- 🛠️ [Runs and installs](#tool-management) Python applications.
+- 🗂️ Provides [comprehensive project management](#project), with a
+  [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
-  [universal lockfile](./concepts/projects/layout.md#the-lockfile).
+- 🐍 [Installs and manages](#python-versions) Python versions.
+- 🛠️ [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.