From 262ca7396533903dc9381d08153b858db28c15cb Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Thu, 5 Jun 2025 12:09:49 -0500 Subject: [PATCH] Remove the configuration section in favor of concepts / reference (#13842) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extends https://github.com/astral-sh/uv/pull/13841 — I'll drop that commit later after that pull request merges but it's small. I find the split into a "Configuration" section awkward and don't think it's helping us. Everything moved into the "Concepts" section, except the "Environment variables" page which definitely belongs in the reference and the "Installer" page which is fairly niche and seems better in the reference. Before / After --- .github/workflows/ci.yml | 2 +- .prettierignore | 2 +- changelogs/0.4.x.md | 2 +- .../uv-dev/src/generate_env_vars_reference.rs | 2 +- .../authentication.md | 0 .../build-backend.md | 0 .../configuration-files.md} | 0 docs/concepts/index.md | 4 ++++ docs/{configuration => concepts}/indexes.md | 0 docs/concepts/projects/dependencies.md | 2 +- docs/concepts/python-versions.md | 2 +- docs/configuration/index.md | 12 ----------- docs/getting-started/installation.md | 2 +- .../guides/integration/alternative-indexes.md | 4 ++-- docs/guides/projects.md | 4 ++-- docs/guides/scripts.md | 6 +++--- docs/pip/compatibility.md | 6 +++--- docs/pip/packages.md | 4 ++-- .../environment.md | 0 .../{configuration => reference}/installer.md | 2 +- mkdocs.template.yml | 20 +++++++++++-------- pyproject.toml | 2 +- 22 files changed, 37 insertions(+), 41 deletions(-) rename docs/{configuration => concepts}/authentication.md (100%) rename docs/{configuration => concepts}/build-backend.md (100%) rename docs/{configuration/files.md => concepts/configuration-files.md} (100%) rename docs/{configuration => concepts}/indexes.md (100%) delete mode 100644 docs/configuration/index.md rename docs/{configuration => reference}/environment.md (100%) rename docs/{configuration => reference}/installer.md (98%) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 12d6e5f91..7e3caec55 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -39,7 +39,7 @@ jobs: while IFS= read -r file; do # Generated markdown and JSON files are checked during test runs. - if [[ "${file}" =~ ^docs/ && ! "${file}" =~ ^docs/reference/(cli|settings).md && ! "${file}" =~ ^docs/configuration/environment.md ]]; then + if [[ "${file}" =~ ^docs/ && ! "${file}" =~ ^docs/reference/(cli|settings).md && ! "${file}" =~ ^docs/reference/environment.md ]]; then echo "Skipping ${file} (matches docs/ pattern)" continue fi diff --git a/.prettierignore b/.prettierignore index dc54f51ff..1f89dc11b 100644 --- a/.prettierignore +++ b/.prettierignore @@ -3,6 +3,6 @@ CHANGELOG.md PREVIEW-CHANGELOG.md docs/reference/cli.md docs/reference/settings.md -docs/configuration/environment.md +docs/reference/environment.md ecosystem/home-assistant-core/LICENSE.md docs/guides/integration/gitlab.md diff --git a/changelogs/0.4.x.md b/changelogs/0.4.x.md index 335780fef..e5f996f69 100644 --- a/changelogs/0.4.x.md +++ b/changelogs/0.4.x.md @@ -960,7 +960,7 @@ argument (or the `UV_INDEX` environment variable); to replace the default index These changes are entirely backwards-compatible with the deprecated `--index-url` and `--extra-index-url` options, which continue to work as before. -See the [Index](https://docs.astral.sh/uv/configuration/indexes/) documentation for more. +See the [Index](https://docs.astral.sh/uv/concepts/indexes/) documentation for more. ### Enhancements diff --git a/crates/uv-dev/src/generate_env_vars_reference.rs b/crates/uv-dev/src/generate_env_vars_reference.rs index 7265200c1..1004b00ef 100644 --- a/crates/uv-dev/src/generate_env_vars_reference.rs +++ b/crates/uv-dev/src/generate_env_vars_reference.rs @@ -21,7 +21,7 @@ pub(crate) fn main(args: &Args) -> anyhow::Result<()> { let filename = "environment.md"; let reference_path = PathBuf::from(ROOT_DIR) .join("docs") - .join("configuration") + .join("reference") .join(filename); match args.mode { diff --git a/docs/configuration/authentication.md b/docs/concepts/authentication.md similarity index 100% rename from docs/configuration/authentication.md rename to docs/concepts/authentication.md diff --git a/docs/configuration/build-backend.md b/docs/concepts/build-backend.md similarity index 100% rename from docs/configuration/build-backend.md rename to docs/concepts/build-backend.md diff --git a/docs/configuration/files.md b/docs/concepts/configuration-files.md similarity index 100% rename from docs/configuration/files.md rename to docs/concepts/configuration-files.md diff --git a/docs/concepts/index.md b/docs/concepts/index.md index a338a5fe7..f9249bd31 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -5,7 +5,11 @@ Read the concept documents to learn more about uv's features: - [Projects](./projects/index.md) - [Tools](./tools.md) - [Python versions](./python-versions.md) +- [Configuration files](./configuration-files.md) +- [Package indexes](./indexes.md) - [Resolution](./resolution.md) +- [The uv build backend](./build-backend.md) +- [Authentication](./authentication.md) - [Caching](./cache.md) - [The pip interface](../pip/index.md) diff --git a/docs/configuration/indexes.md b/docs/concepts/indexes.md similarity index 100% rename from docs/configuration/indexes.md rename to docs/concepts/indexes.md diff --git a/docs/concepts/projects/dependencies.md b/docs/concepts/projects/dependencies.md index 2c68f92a4..42a579695 100644 --- a/docs/concepts/projects/dependencies.md +++ b/docs/concepts/projects/dependencies.md @@ -42,7 +42,7 @@ field. The dependency will include a constraint, e.g., `>=0.27.2`, for the most recent, compatible version of the package. The kind of bound can be adjusted with -[`--bounds`](../../reference/settings.md#bounds), or the constraint can be provided directly: +[`--bounds`](../../reference/settings.md#add-bounds), or the constraint can be provided directly: ```console $ uv add "httpx>=0.20" diff --git a/docs/concepts/python-versions.md b/docs/concepts/python-versions.md index 508ee2440..016d9e00d 100644 --- a/docs/concepts/python-versions.md +++ b/docs/concepts/python-versions.md @@ -284,7 +284,7 @@ during `uv python install`. !!! tip The `python-downloads` setting can be set in a - [persistent configuration file](../configuration/files.md) to change the default behavior, or + [persistent configuration file](./configuration-files.md) to change the default behavior, or the `--no-python-downloads` flag can be passed to any uv command. ## Requiring or disabling managed Python versions diff --git a/docs/configuration/index.md b/docs/configuration/index.md deleted file mode 100644 index 813519629..000000000 --- a/docs/configuration/index.md +++ /dev/null @@ -1,12 +0,0 @@ -# Configuration overview - -Read about the various ways to configure uv: - -- [Using configuration files](./files.md) -- [Using environment variables](./environment.md) -- [Configuring authentication](./authentication.md) -- [Configuring package indexes](./indexes.md) -- [The uv build backend](build-backend.md) - -Or, jump to the [settings reference](../reference/settings.md) which enumerates the available -configuration options. diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 1638c8871..6edcafa28 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -62,7 +62,7 @@ uv provides a standalone installer to download and install uv: Alternatively, the installer or binaries can be downloaded directly from [GitHub](#github-releases). -See the documentation on [installer configuration](../configuration/installer.md) for details on +See the reference documentation on the [installer](../reference/installer.md) for details on customizing your uv installation. ### PyPI diff --git a/docs/guides/integration/alternative-indexes.md b/docs/guides/integration/alternative-indexes.md index 7ef6300e3..52ec6e365 100644 --- a/docs/guides/integration/alternative-indexes.md +++ b/docs/guides/integration/alternative-indexes.md @@ -8,8 +8,8 @@ description: # Using alternative package indexes While uv uses the official Python Package Index (PyPI) by default, it also supports -[alternative package indexes](../../configuration/indexes.md). Most alternative indexes require -various forms of authentication, which require some initial setup. +[alternative package indexes](../../concepts/indexes.md). Most alternative indexes require various +forms of authentication, which require some initial setup. !!! important diff --git a/docs/guides/projects.md b/docs/guides/projects.md index b86d02861..0fd97eb0d 100644 --- a/docs/guides/projects.md +++ b/docs/guides/projects.md @@ -87,8 +87,8 @@ description or license. You can edit this file manually, or use commands like `u See the official [`pyproject.toml` guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) for more details on getting started with the `pyproject.toml` format. -You'll also use this file to specify uv [configuration options](../configuration/files.md) in a -[`[tool.uv]`](../reference/settings.md) section. +You'll also use this file to specify uv [configuration options](../concepts/configuration-files.md) +in a [`[tool.uv]`](../reference/settings.md) section. ### `.python-version` diff --git a/docs/guides/scripts.md b/docs/guides/scripts.md index 90816c9f9..7142db155 100644 --- a/docs/guides/scripts.md +++ b/docs/guides/scripts.md @@ -252,8 +252,8 @@ print(httpx.get("https://example.com")) ## Using alternative package indexes -If you wish to use an alternative [package index](../configuration/indexes.md) to resolve -dependencies, you can provide the index with the `--index` option: +If you wish to use an alternative [package index](../concepts/indexes.md) to resolve dependencies, +you can provide the index with the `--index` option: ```console $ uv add --index "https://example.com/simple" --script example.py 'requests<3' 'rich' @@ -267,7 +267,7 @@ This will include the package data in the inline metadata: ``` If you require authentication to access the package index, then please refer to the -[package index](../configuration/indexes.md) documentation. +[package index](../concepts/indexes.md) documentation. ## Locking dependencies diff --git a/docs/pip/compatibility.md b/docs/pip/compatibility.md index 7898ea7b8..30c14827d 100644 --- a/docs/pip/compatibility.md +++ b/docs/pip/compatibility.md @@ -36,7 +36,7 @@ drawbacks: Instead, uv supports its own environment variables, like `UV_INDEX_URL`. uv also supports persistent configuration in a `uv.toml` file or a `[tool.uv.pip]` section of `pyproject.toml`. For more -information, see [Configuration files](../configuration/files.md). +information, see [Configuration files](../concepts/configuration-files.md). ## Pre-release compatibility @@ -120,8 +120,8 @@ While `unsafe-best-match` is the closest to `pip`'s behavior, it exposes users t "dependency confusion" attacks. uv also supports pinning packages to dedicated indexes (see: -[_Indexes_](../configuration/indexes.md#pinning-a-package-to-an-index)), such that a given package -is _always_ installed from a specific index. +[_Indexes_](../concepts/indexes.md#pinning-a-package-to-an-index)), such that a given package is +_always_ installed from a specific index. ## PEP 517 build isolation diff --git a/docs/pip/packages.md b/docs/pip/packages.md index ccd4da19a..a47b1aa0e 100644 --- a/docs/pip/packages.md +++ b/docs/pip/packages.md @@ -57,8 +57,8 @@ $ # Install a branch $ uv pip install "git+https://github.com/astral-sh/ruff@main" ``` -See the [Git authentication](../configuration/authentication.md#git-authentication) documentation -for installation from a private repository. +See the [Git authentication](../concepts/authentication.md#git-authentication) documentation for +installation from a private repository. ## Editable packages diff --git a/docs/configuration/environment.md b/docs/reference/environment.md similarity index 100% rename from docs/configuration/environment.md rename to docs/reference/environment.md diff --git a/docs/configuration/installer.md b/docs/reference/installer.md similarity index 98% rename from docs/configuration/installer.md rename to docs/reference/installer.md index 0082217f5..8db77ba5d 100644 --- a/docs/configuration/installer.md +++ b/docs/reference/installer.md @@ -1,4 +1,4 @@ -# Configuring the uv installer +# The uv installer ## Changing the install path diff --git a/mkdocs.template.yml b/mkdocs.template.yml index 5e14d676e..9a4d3b1cb 100644 --- a/mkdocs.template.yml +++ b/mkdocs.template.yml @@ -74,6 +74,12 @@ plugins: "reference/versioning.md": "reference/policies/versioning.md" "reference/platforms.md": "reference/policies/platforms.md" "reference/build_failures.md": "reference/troubleshooting/build-failures.md" + "configuration/installer.md": "reference/installer.md" + "configuration/authentication.md": "concepts/authentication.md" + "configuration/build-backend.md": "concepts/build-backend.md" + "configuration/files.md": "concepts/configuration-files.md" + "configuration/indexes.md": "concepts/indexes.md" + "configuration/environment.md": "reference/environment.md" extra_css: - stylesheets/extra.css extra_javascript: @@ -132,7 +138,11 @@ nav: - Using workspaces: concepts/projects/workspaces.md - Tools: concepts/tools.md - Python versions: concepts/python-versions.md + - Configuration files: concepts/configuration-files.md + - Package indexes: concepts/indexes.md - Resolution: concepts/resolution.md + - Build backend: concepts/build-backend.md + - Authentication: concepts/authentication.md - Caching: concepts/cache.md # Note: The `pip` section was moved to the `concepts/` section but the # top-level directory structure was retained to ease the transition. @@ -144,18 +154,12 @@ nav: - Declaring dependencies: pip/dependencies.md - Locking environments: pip/compile.md - Compatibility with pip: pip/compatibility.md - - Configuration: - - configuration/index.md - - Configuration files: configuration/files.md - - Environment variables: configuration/environment.md - - Authentication: configuration/authentication.md - - Package indexes: configuration/indexes.md - - Installer: configuration/installer.md - - Build backend: configuration/build-backend.md - Reference: - reference/index.md - Commands: reference/cli.md - Settings: reference/settings.md + - Environment variables: reference/environment.md + - Installer: reference/installer.md - Troubleshooting: - reference/troubleshooting/index.md - Build failures: reference/troubleshooting/build-failures.md diff --git a/pyproject.toml b/pyproject.toml index 2dbeb55c1..745081d7a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -86,7 +86,7 @@ version_files = [ "docs/guides/integration/pre-commit.md", "docs/guides/integration/github.md", "docs/guides/integration/aws-lambda.md", - "docs/configuration/build-backend.md", + "docs/concepts/build-backend.md", ] [tool.mypy]