Bundle of documentation changes (#5307)

Following #5239

docs/configuration/files.md

@@ -8,7 +8,7 @@ in the nearest parent directory.
 If a `pyproject.toml` file is found, uv will read configuration from the `[tool.uv.pip]` table.
 For example, to set a persistent index URL, add the following to a `pyproject.toml`:
 
-```toml
+```toml title="project.toml"
 [tool.uv.pip]
 index-url = "https://test.pypi.org/simple"
 ```
@@ -18,7 +18,7 @@ the directory hierarchy.)
 
 If a `uv.toml` file is found, uv will read from the `[pip]` table. For example:
 
-```toml
+```toml title="uv.toml"
 [pip]
 index-url = "https://test.pypi.org/simple"
 ```

docs/dependencies.md

@@ -19,7 +19,7 @@ standard.
 `project.dependencies` is structured as a list. Each entry includes a dependency name and
 version. An entry may include extras or environment markers for platform-specific packages. For example:
 
-```toml
+```toml title="pyproject.toml"
 [project]
 name = "albatross"
 version = "0.1.0"
@@ -37,41 +37,126 @@ dependencies = [
 ]
 ```
 
-If the project only requires packages from standaard 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.
+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.
 
 ## Dependency sources
 
-During development, the project may rely on a package that isn't available on PyPI. In the following example, the project will require several package sources:
+During development, the project may rely on a package that isn't available on PyPI. The following additional sources are supported by uv:
 
-- `tqdm` from a specific Git commit
-- `importlib_metadata` from a dedicated URL
-- `torch` from the PyTorch-specific index
-- `mollymawk` from the current workspace
+- Git
+- URL
+- Path
+- Workspace
 
-These requirements can be expressed by extending the definitions in the `project.dependencies` table with `tool.uv.sources` entries:
+Only a single source may be defined for each dependency.
+
+Note that if a non-uv project uses a project with sources as a Git- or path-dependency, only
+`project.dependencies` is respected, the information in the source table
+will need to be re-specified in a format specific to the other package manager.
+
+### Git
+
+To add a Git dependency source, prefix a Git-compatible URL to clone with `git+`.
 
-```toml
+For example:
+
+```console
+$ uv add git+https://github.com/encode/httpx
+```
+
+Will result in a `pyproject.toml` with:
+
+```toml title="pyproject.toml"
+[project]
+dependencies = [
+    "httpx",
+]
+
+[tool.uv.sources]
+httpx = { git = "https://github.com/encode/httpx" }
+```
+
+A revision, tag, or branch may also be included, e.g.:
+
+```console
+$ uv add git+https://github.com/encode/httpx --tag 0.27.0
+$ uv add git+https://github.com/encode/httpx --branch main
+$ uv add git+https://github.com/encode/httpx --rev 326b943
+```
+
+Git dependencies can also be manually added or edited in the `pyproject.toml` with the `{ git = <url> }` syntax. A target revision may be specified with one of: `rev`, `tag`, or `branch`. A `subdirectory` may be specified if the package isn't in the repository root.
+
+### URL
+
+To add a URL source, provide a `https://` URL to either a wheel (ending in `.whl`) or a source distribution (ending in `.zip` or `.tar.gz`).
+
+For example:
+
+```console
+$ uv add "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz"
+```
+
+Will result in a `pyproject.toml` with:
+
+```toml title="pyproject.toml"
+[project]
+dependencies = [
+    "httpx",
+]
+
+[tool.uv.sources]
+httpx = { url = "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz" }
+```
+
+URL dependencies can also be manually added or edited in the `pyproject.toml` with the `{ url = <url> }` syntax.  A `subdirectory` may be specified if the if the source distribution isn't in the archive root.
+
+### Path
+
+To add a path source, provide the path of a wheel (ending in `.whl`), a source distribution (ending in `.zip` or `.tar.gz`), or a directory containing a `pyproject.toml`.
+
+For example:
+
+```console
+$ uv add /example/foo.whl
+```
+
+Will result in a `pyproject.toml` with:
+
+```toml title="pyproject.toml"
+[project]
+dependencies = [
+    "foo",
+]
+
+[tool.uv.sources]
+foo = { path = "/example/foo.whl" }
+```
+
+The path may also be a relative path, e.g.:
+
+```console
+$ uv add ./foo
+```
+
+Note an [editable installation](#editables-dependencies) is not used for path dependencies. However, for directories, an editable installation may be requested, e.g.:
+
+```console
+$ uv add --editable ./foo
+```
+
+However, it is recommended to use [_workspaces_](#workspaces) instead of manual path dependencies. 
+
+### Workspace member
+
+To declare a workspace member, add the dependency with `{ workspace = true }`. All workspace members must be explicitly stated. Workspace members are [editable](#editables-dependencies) by default; `editable = false` may be included to install them as regular dependencies. See the [workspace](./workspaces.md) documentation for more details on workspaces.
+
+```toml title="pyproject.toml"
 [project]
-name = "albatross"
-version = "0.1.0"
 dependencies = [
-  # Any version in this range.
-  "tqdm >=4.66.2,<5",
-  # Exactly this version of torch.
-  "torch ==2.2.2",
-  # Install transformers with the torch extra.
-  "transformers[torch] >=4.39.3,<5",
-  # Only install this package on Python versions prior to 3.10.
-  "importlib_metadata >=7.1.0,<8; python_version < '3.10'",
   "mollymawk ==0.1.0"
 ]
 
 [tool.uv.sources]
-# Install a specific Git commit.
-tqdm = { git = "https://github.com/tqdm/tqdm", rev = "cc372d09dcd5a5eabdc6ed4cf365bdb0be004d44" }
-# Install a remote source distribution (`.zip`, `.tar.gz`) or wheel (`.whl`).
-importlib_metadata = { url = "https://github.com/python/importlib_metadata/archive/refs/tags/v7.1.0.zip" }
-# Use a package included in the same workspace (as an editable installation).
 mollymawk = { workspace = true }
 
 [tool.uv.workspace]
@@ -80,22 +165,6 @@ include = [
 ]
 ```
 
-uv supports the following sources:
-
-- **Git**: `git = <url>`. A git-compatible URL to clone. A target revision may be specified with one of: `rev`, `tag`, or `branch`. A `subdirectory` may be specified if the package isn't in the repository root.
-- **URL**: `url = <url>`. An `https://` URL to either a wheel (ending in `.whl`) or a source distribution
-  (ending in `.zip` or `.tar.gz`). A `subdirectory` may be specified if the if the source distribution isn't in the archive root.
-- **Path**: `path = <path>`. A path to a wheel (ending in `.whl`), a source
-  distribution (ending in `.zip` or `.tar.gz`), or a directory containing a `pyproject.toml`. 
-  The path may be absolute or relative path. It is recommended to use _workspaces_ instead of manual path dependencies. For directories, `editable = true` may be specified for an [editable](#editables-dependencies) installation.
-- **Workspace**: `workspace = true`. All workspace dependencies must be explicitly stated. Workspace dependencies are [editable](#editables-dependencies) by default; `editable = false` may be specified to install them as regular dependencies. See the [workspace](./workspaces.md) documentation for more details on workspaces.
-
-Only a single source may be defined for each dependency.
-
-Note that if a non-uv project uses this project as a Git- or path-dependency, only
-`project.dependencies` is respected, the information in the source table
-will need to be specified in a format specific to the other package manager.
-
 ## Optional dependencies
 
 It is common for projects that are published as libraries to make some features optional to reduce the default dependency tree. For example,
@@ -107,7 +176,7 @@ from extra name to its dependencies, following [PEP 508](#pep-508) syntax.
 
 Optional dependencies can have entries in `tool.uv.sources` the same as normal dependencies.
 
-```toml
+```toml title="pyproject.toml"
 [project]
 name = "pandas"
 version = "1.0.0"
@@ -126,19 +195,31 @@ excel = [
 ]
 ```
 
+To add an optional dependency, use the `--optional <extra>` option:
+
+```console
+$ uv add httpx --optional network
+```
+
 ## Development dependencies
 
 Unlike optional dependencies, development dependencies are local-only and will _not_ be included in the project requirements when published to PyPI or other indexes. As such, development dependencies are included under `[tool.uv]` instead of `[project]`. 
 
 Development dependencies can have entries in `tool.uv.sources` the same as normal dependencies.
 
-```toml
+```toml title="pyproject.toml"
 [tool.uv]
 dev-dependencies = [
   "pytest >=8.1.1,<9"
 ]
 ```
 
+To add a development dependency, include the `--dev` flag:
+
+```console
+$ uv add ruff --dev`
+```
+
 ## PEP 508
 
 [PEP 508](https://peps.python.org/pep-0508/) defines a syntax for dependency specification. It is composed of, in order:
@@ -182,4 +263,16 @@ There are some limitations to editables (mainly: the build backend needs to supp
 native modules aren't recompiled before import), but they are useful for development, as the
 virtual environment will always use the latest changes to the package.
 
-uv uses editable installation for workspace packages and patched dependencies by default.
+uv uses editable installation for workspace packages by default.
+
+To add an editable dependency, use the `--editable` flag:
+
+```console
+$ uv add --editable ./path/foo
+```
+
+Or, to opt-out of using an editable dependency in a workspace:
+
+```console
+$ uv add --no-editable ./path/foo
+```

docs/features.md

@@ -1,5 +1,5 @@
 
-# Feature overview
+# Features
 
 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.
 
@@ -100,24 +100,4 @@ Managing and inspecting uv's state, such as the cache, storage directories, or p
 
 ## Next steps
 
-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)
+Check out the [documentation overview](./overview.md) for a list of guides and concepts.

docs/guides/integration/commercial-indexes.md

@@ -33,3 +33,7 @@ export UV_KEYRING_PROVIDER=subprocess
 # Configure the index URL with the username
 export UV_EXTRA_INDEX_URL=https://VssSessionToken@pkgs.dev.azure.com/{organisation}/{project}/_packaging/{feedName}/pypi/simple/
 ```
+
+## Other indexes
+
+uv is also known to work with JFrog's Artifactory, the Google Cloud Artifact Registry, and AWS Code Artifact.

docs/guides/integration/docker.md

@@ -12,14 +12,14 @@ docker run ghcr.io/astral-sh/uv --help
 
 uv can be installed by copying from the official Docker image:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 FROM python:3.12-slim-bullseye
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
 ```
 
 Or with the standalone installer:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 FROM python:3.12-slim-bullseye
 RUN apt-get update && apt-get install -y curl --no-install-recommends
 RUN curl -LsSf https://astral.sh/uv/install.sh | sh
@@ -36,19 +36,19 @@ Once uv is installed in an image, it can be used to install some packages.
 
 The system Python environment is safe to use this context, since a container is already isolated. The `--system` flag can be used to install in the system environment:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 RUN uv pip install --system ruff
 ```
 
 To use the system Python environment by default, set the `UV_SYSTEM_PYTHON` variable:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 ENV UV_SYSTEM_PYTHON=1
 ```
 
 Alternatively, a virtual environment can be created and activated:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 RUN uv venv /opt/venv
 # Use the virtual environment automatically
 ENV VIRTUAL_ENV=/opt/venv
@@ -58,15 +58,15 @@ ENV PATH="/opt/venv/bin:$PATH"
 
 When using a virtual environment, the `--system` flag should be omitted from uv invocations:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 RUN uv pip install ruff
 ```
 
 ## Installing requirements
 
 To install requirements files, copy them into the container:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 COPY requirements.txt .
 RUN uv pip install -r requirements.txt
 ```
@@ -75,7 +75,7 @@ RUN uv pip install -r requirements.txt
 
 When installing a project alongside requirements, it is prudent to separate copying the requirements from the rest of the source code. This allows the dependencies of the project (which do not change often) to be cached separately from the project itself (which changes very frequently).
 
-```dockerfile
+```dockerfile title="Dockerfile"
 COPY pyproject.toml .
 RUN uv pip install -r pyproject.toml
 COPY . .
@@ -88,7 +88,7 @@ RUN uv pip install -e .
 
 If uv isn't needed in the final image, the binary can be mounted in each invocation:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 RUN --mount=from=uv,source=/uv,target=/bin/uv \
     uv pip install --system ruff
 ```
@@ -97,15 +97,15 @@ RUN --mount=from=uv,source=/uv,target=/bin/uv \
 
 A [cache mount](https://docs.docker.com/build/guide/mounts/#add-a-cache-mount) can be used to improve performance across builds:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 RUN --mount=type=cache,target=/root/.cache/uv \
  ./uv pip install -r requirements.txt -->
 ```
 
 Note the cache directory's location can be determined with the `uv cache dir` command.
 Alternatively, the cache can be set to a constant location:
 
-```dockerfile
+```dockerfile title="Dockerfile"
 ENV UV_CACHE_DIR=/opt/uv-cache/
 ```