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 12d6e5f916..7e3caec55d 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 dc54f51fff..1f89dc11b5 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 335780fef5..e5f996f69b 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 7265200c10..1004b00ef8 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 a338a5fe75..f9249bd314 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 2c68f92a45..42a5796951 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 508ee2440a..016d9e00da 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 813519629e..0000000000 --- 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 1638c88712..6edcafa283 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 7ef6300e3e..52ec6e365f 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 b86d02861b..0fd97eb0db 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 90816c9f95..7142db1554 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 7898ea7b8e..30c14827d2 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 ccd4da19a7..a47b1aa0ee 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 0082217f5c..8db77ba5d6 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 5e14d676ef..9a4d3b1cbe 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 2dbeb55c1a..745081d7a9 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]