Add mdbook

astral-sh · Jun 23, 2024 · 4bdd5b1 · 4bdd5b1
1 parent a96f967
commit 4bdd5b1
Show file tree

Hide file tree

Showing 32 changed files with 1,606 additions and 191 deletions.
diff --git a/PIP-COMPATIBILITY.md b/PIP-COMPATIBILITY.md
diff --git a/PIP_COMPATIBILITY.md b/PIP_COMPATIBILITY.md
diff --git a/README.md b/README.md
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1 @@
+book
diff --git a/docs/README.md b/docs/README.md
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -0,0 +1,44 @@
+# Summary
+
+- [Introduction](introduction.md)
+
+# Getting started
+
+- [Installing uv](installation.md)
+- [Python environments](pip/environments.md)
+- [Managing packages](pip/packages.md)
+- [Inspecting environments](pip/inspection.md)
+- [Locking environments](pip/compile.md)
+
+# Configuration
+
+- [Configuration files](configuration/files.md)
+- [Environment variables](configuration/environment.md)
+- [Authentication](configuration/authentication.md)
+
+# Advanced usage
+
+- [Python discovery](python/discovery.md)
+- [Resolution](resolution.md)
+- [Caching](cache.md)
+
+# Integration guides
+
+- [Using in Docker](guides/docker.md)
+- [Using in GitHub Actions](guides/github.md)
+- [Using with pre-commit](guides/pre-commit.md)
+
+# Preview features
+
+- [Introduction](preview/introduction.md)
+- [Projects](preview/projects.md)
+- [Dependency specification](preview/dependencies.md)
+- [Workspaces](preview/workspaces.md)
+- [Command-line tools](preview/tools.md)
+- [Python toolchains](preview/toolchains.md)
+
+# Policies
+
+- [Versioning](versioning.md)
+- [Platform support](platforms.md)
+- [Compatibility with pip](pip/compatibility.md)
diff --git a/docs/book.toml b/docs/book.toml
@@ -0,0 +1,9 @@
+[book]
+language = "en"
+multilingual = false
+src = "."
+title = "uv"
+
+[output.html]
+no-section-label = true
+additional-css = ["style.css"]
diff --git a/docs/authentication.md → docs/configuration/authentication.md b/docs/authentication.md → docs/configuration/authentication.md
diff --git a/docs/configuration.md → docs/configuration/environment.md b/docs/configuration.md → docs/configuration/environment.md
@@ -1,52 +1,4 @@
-# Configuration
-
-## Persistent configuration
-
-uv supports persistent configuration at both the project- and user-level.
-
-Specifically, uv will search for a `pyproject.toml` or `uv.toml` file in the current directory, or
-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
-[tool.uv.pip]
-index-url = "https://test.pypi.org/simple"
-```
-
-(If there is no such table, the `pyproject.toml` file will be ignored, and uv will continue searching in
-the directory hierarchy.)
-
-If a `uv.toml` file is found, uv will read from the `[pip]` table. For example:
-
-```toml
-[pip]
-index-url = "https://test.pypi.org/simple"
-```
-
-uv will also discover user-level configuration at `~/.config/uv/uv.toml` (or
-`$XDG_CONFIG_HOME/uv/uv.toml`) on macOS and Linux, or `%APPDATA%\uv\uv.toml` on Windows. User-level
-configuration must use the `uv.toml` format, rather than the `pyproject.toml` format, as a
-`pyproject.toml` is intended to define a Python _project_.
-
-If both project- and user-level configuration are found, the settings will be merged, with the
-project-level configuration taking precedence. Specifically, if a string, number, or boolean is
-present in both tables, the project-level value will be used, and the user-level value will be
-ignored. If an array is present in both tables, the arrays will be concatenated, with the
-project-level settings appearing earlier in the merged array.
-
-Settings provided via environment variables take precedence over persistent configuration, and
-settings provided via the command line take precedence over both.
-
-uv accepts a `--isolated` command-line argument which, when provided, disables the discovery of any
-persistent configuration.
-
-uv also accepts a `--config-file` command-line argument, which accepts a path to a `uv.toml` to use
-as the configuration file. When provided, this file will be used in place of _any_ discovered
-configuration files (e.g., user-level configuration will be ignored).
-
-## Environment variables
+# Environment variables
 
 uv accepts the following command-line arguments as environment variables:
 

diff --git a/docs/configuration/files.md b/docs/configuration/files.md
@@ -0,0 +1,45 @@
+# Configuration files
+
+uv supports persistent configuration files at both the project- and user-level.
+
+Specifically, uv will search for a `pyproject.toml` or `uv.toml` file in the current directory, or
+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
+[tool.uv.pip]
+index-url = "https://test.pypi.org/simple"
+```
+
+(If there is no such table, the `pyproject.toml` file will be ignored, and uv will continue searching in
+the directory hierarchy.)
+
+If a `uv.toml` file is found, uv will read from the `[pip]` table. For example:
+
+```toml
+[pip]
+index-url = "https://test.pypi.org/simple"
+```
+
+uv will also discover user-level configuration at `~/.config/uv/uv.toml` (or
+`$XDG_CONFIG_HOME/uv/uv.toml`) on macOS and Linux, or `%APPDATA%\uv\uv.toml` on Windows. User-level
+configuration must use the `uv.toml` format, rather than the `pyproject.toml` format, as a
+`pyproject.toml` is intended to define a Python _project_.
+
+If both project- and user-level configuration are found, the settings will be merged, with the
+project-level configuration taking precedence. Specifically, if a string, number, or boolean is
+present in both tables, the project-level value will be used, and the user-level value will be
+ignored. If an array is present in both tables, the arrays will be concatenated, with the
+project-level settings appearing earlier in the merged array.
+
+Settings provided via environment variables take precedence over persistent configuration, and
+settings provided via the command line take precedence over both.
+
+uv accepts a `--isolated` command-line argument which, when provided, disables the discovery of any
+persistent configuration.
+
+uv also accepts a `--config-file` command-line argument, which accepts a path to a `uv.toml` to use
+as the configuration file. When provided, this file will be used in place of _any_ discovered
+configuration files (e.g., user-level configuration will be ignored).
diff --git a/docs/docker.md → docs/guides/docker.md b/docs/docker.md → docs/guides/docker.md
@@ -1,22 +1,31 @@
 # Using uv in Docker
 
+## Running in Docker
+
+A Docker image is published with a built version of uv available. To run a uv command in a container:
+
+```bash
+docker run ghcr.io/astral-sh/uv --help
+```
+
 ## Installing uv
 
-uv can be installed by copying from our Docker image:
+uv can be installed by copying from the official Docker image:
 
 ```dockerfile
 FROM ghcr.io/astral-sh/uv:latest as uv
 FROM python:3.12-slim-bullseye
 COPY --from=uv /uv /bin/uv
 ```
 
-Or with our standalone installer:
+Or with the standalone installer:
 
 ```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
-ENV PATH="/root/.cargo/bin/:$PATH"
+ENV PATH="/root/.cargo/bin/:
+$PATH"
 ```
 
 Note this requires `curl` to be available.

diff --git a/docs/guides/pre-commit.md b/docs/guides/pre-commit.md
@@ -0,0 +1,45 @@
+# Using uv in pre-commit
+
+An official pre-commit hook is provided at [`astral-sh/uv-pre-commit`](https://github.com/astral-sh/uv-pre-commit).
+
+To compile requirements via pre-commit, add the following to the `.pre-commit-config.yaml`:
+
+```yaml
+- repo: https://github.com/astral-sh/uv-pre-commit
+  # uv version.
+  rev: 0.2.13
+  hooks:
+    # Compile requirements
+    - id: pip-compile
+      args: [requirements.in, -o, requirements.txt]
+```
+
+To compile alternative files, modify `args` and `files`:
+
+```yaml
+- repo: https://github.com/astral-sh/uv-pre-commit
+  # uv version.
+  rev: 0.2.13
+  hooks:
+    # Compile requirements
+    - id: pip-compile
+      args: [requirements-dev.in, -o, requirements-dev.txt]
+      files: ^requirements-dev\.(in|txt)$
+```
+
+To run the hook over multiple files at the same time:
+
+```yaml
+- repo: https://github.com/astral-sh/uv-pre-commit
+  # uv version.
+  rev: 0.2.13
+  hooks:
+    # Compile requirements
+    - id: pip-compile
+      name: pip-compile requirements.in
+      args: [requirements.in, -o, requirements.txt]
+    - id: pip-compile
+      name: pip-compile requirements-dev.in
+      args: [requirements-dev.in, -o, requirements-dev.txt]
+      files: ^requirements-dev\.(in|txt)$
+```
diff --git a/docs/installation.md b/docs/installation.md
@@ -6,7 +6,7 @@ Install uv with our standalone installers, from PyPI, or from your package manag
 
 uv provides a standalone installer that downloads and installs uv:
 
-```shell
+```bash
 # On macOS and Linux.
 curl -LsSf https://astral.sh/uv/install.sh | sh
 
@@ -18,7 +18,7 @@ uv is installed to `~/.cargo/bin`.
 
 A specific release can be requested by including the version in the URL:
 
-```
+```bash
 # On macOS and Linux.
 curl -LsSf https://astral.sh/uv/0.2.11/install.sh | sh
 
@@ -28,7 +28,7 @@ powershell -c "irm https://astral.sh/uv/0.2.11/install.ps1 | iex"
 
 When the standalone installer is used, uv can upgrade itself.
 
-```shell
+```bash
 uv self update
 ```
 
@@ -40,20 +40,26 @@ For convenience, uv is published to [PyPI](https://pypi.org/project/uv/). When i
 
 If installing from PyPI, we recommend using `pipx` to install uv into an isolated environment:
 
-```shell
+```bash
 pipx install uv
 ```
 
 However, `pip` can also be used:
 
-```shell
+```bash
 pip install uv
 ```
 
 ## Homebrew
 
 uv is available in the core Homebrew packages.
 
-```shell
+```bash
 brew install uv
 ```
+
+## Docker
+
+uv provides a Docker image at [`ghcr.io/astral-sh/uv`](https://github.com/astral-sh/uv/pkgs/container/uv).
+
+See our guide on [using uv in Docker](./guides/docker.md) for more details.