Python
/
uv
mirror of https://github.com/astral-sh/uv
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs(settings): bunch of fixes and improvements (#5177) 

## Summary

Spotted some issues in the settings documentation, and room for small
improvements by linking to PEPs/RFCs.

Also updating contribution documentation to mention that it's necessary
to enable the virtual environment before running `mkdocs serve`.

## Test Plan

Running documentation locally.
This commit is contained in:
Mathieu Kniewallner 2024-07-19 16:32:21 +02:00 committed by GitHub
parent b1a350cb9f
commit f2e2825d1b
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 72 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
CONTRIBUTING.md
View File

@ -127,11 +127,21 @@ To preview any changes to the documentation locally:
# For contributors. # For contributors.
uv pip install -r docs/requirements.txt uv pip install -r docs/requirements.txt
# Or, for members of the Astral org, which has access to MkDocs Insiders via sponsorship. # Or, for members of the Astral org, which has access to MkDocs Insiders via sponsorship.
uv pip install -r docs/requirements-insiders.txt uv pip install -r docs/requirements-insiders.txt
``` ```
1. Activate the virtual environment with:
```shell
# On macOS and Linux.
source .venv/bin/activate
# On Windows.
.venv\Scripts\activate
```
1. Run the development server with: 1. Run the development server with:
```shell ```shell

45
crates/uv-settings/src/settings.rs
View File

@ -129,7 +129,7 @@ pub struct GlobalOptions {
default = "\"automatic\"", default = "\"automatic\"",
value_type = "str", value_type = "str",
example = r#" example = r#"
python-fetch = \"automatic\" python-fetch = "manual"
"#, "#,
possible_values = true possible_values = true
)] )]
@ -194,8 +194,8 @@ pub struct ResolverOptions {
pub struct ResolverInstallerOptions { pub struct ResolverInstallerOptions {
/// The URL of the Python package index (by default: <https://pypi.org/simple>). /// The URL of the Python package index (by default: <https://pypi.org/simple>).
/// ///
/// Accepts either a repository compliant with PEP 503 (the simple repository API), or a local /// Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/)
/// directory laid out in the same format. /// (the simple repository API), or a local directory laid out in the same format.
/// ///
/// The index provided by this setting is given lower priority than any indexes specified via /// The index provided by this setting is given lower priority than any indexes specified via
/// [`extra_index_url`](#extra-index-url). /// [`extra_index_url`](#extra-index-url).
@ -203,14 +203,14 @@ pub struct ResolverInstallerOptions {
default = "\"https://pypi.org/simple\"", default = "\"https://pypi.org/simple\"",
value_type = "str", value_type = "str",
example = r#" example = r#"
index-url = "https://pypi.org/simple" index-url = "https://test.pypi.org/simple"
"# "#
)] )]
pub index_url: Option<IndexUrl>, pub index_url: Option<IndexUrl>,
/// Extra URLs of package indexes to use, in addition to `--index-url`. /// Extra URLs of package indexes to use, in addition to `--index-url`.
/// ///
/// Accepts either a repository compliant with PEP 503 (the simple repository API), or a local /// Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/)
/// directory laid out in the same format. /// (the simple repository API), or a local directory laid out in the same format.
/// ///
/// All indexes provided via this flag take priority over the index specified by /// All indexes provided via this flag take priority over the index specified by
/// [`index_url`](#index-url). When multiple indexes are provided, earlier values take priority. /// [`index_url`](#index-url). When multiple indexes are provided, earlier values take priority.
@ -305,7 +305,8 @@ pub struct ResolverInstallerOptions {
possible_values = true possible_values = true
)] )]
pub prerelease: Option<PreReleaseMode>, pub prerelease: Option<PreReleaseMode>,
/// Settings to pass to the PEP 517 build backend, specified as `KEY=VALUE` pairs. /// Settings to pass to the [PEP 517](https://peps.python.org/pep-0517/) build backend,
/// specified as `KEY=VALUE` pairs.
#[option( #[option(
default = "{}", default = "{}",
value_type = "dict", value_type = "dict",
@ -316,8 +317,8 @@ pub struct ResolverInstallerOptions {
pub config_settings: Option<ConfigSettings>, pub config_settings: Option<ConfigSettings>,
/// Limit candidate packages to those that were uploaded prior to the given date. /// Limit candidate packages to those that were uploaded prior to the given date.
/// ///
/// Accepts both RFC 3339 timestamps (e.g., `2006-12-02T02:07:43Z`) and UTC dates in the same /// Accepts both [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) timestamps (e.g.,
/// format (e.g., `2006-12-02`). /// `2006-12-02T02:07:43Z`) and UTC dates in the same format (e.g., `2006-12-02`).
#[option( #[option(
default = "None", default = "None",
value_type = "str", value_type = "str",
@ -527,8 +528,8 @@ pub struct PipOptions {
pub prefix: Option<PathBuf>, pub prefix: Option<PathBuf>,
/// The URL of the Python package index (by default: <https://pypi.org/simple>). /// The URL of the Python package index (by default: <https://pypi.org/simple>).
/// ///
/// Accepts either a repository compliant with PEP 503 (the simple repository API), or a local /// Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/)
/// directory laid out in the same format. /// (the simple repository API), or a local directory laid out in the same format.
/// ///
/// The index provided by this setting is given lower priority than any indexes specified via /// The index provided by this setting is given lower priority than any indexes specified via
/// [`extra_index_url`](#extra-index-url). /// [`extra_index_url`](#extra-index-url).
@ -536,14 +537,14 @@ pub struct PipOptions {
default = "\"https://pypi.org/simple\"", default = "\"https://pypi.org/simple\"",
value_type = "str", value_type = "str",
example = r#" example = r#"
index-url = "https://pypi.org/simple" index-url = "https://test.pypi.org/simple"
"# "#
)] )]
pub index_url: Option<IndexUrl>, pub index_url: Option<IndexUrl>,
/// Extra URLs of package indexes to use, in addition to `--index-url`. /// Extra URLs of package indexes to use, in addition to `--index-url`.
/// ///
/// Accepts either a repository compliant with PEP 503 (the simple repository API), or a local /// Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/)
/// directory laid out in the same format. /// (the simple repository API), or a local directory laid out in the same format.
/// ///
/// All indexes provided via this flag take priority over the index specified by /// All indexes provided via this flag take priority over the index specified by
/// [`index_url`](#index-url). When multiple indexes are provided, earlier values take priority. /// [`index_url`](#index-url). When multiple indexes are provided, earlier values take priority.
@ -659,7 +660,8 @@ pub struct PipOptions {
pub only_binary: Option<Vec<PackageNameSpecifier>>, pub only_binary: Option<Vec<PackageNameSpecifier>>,
/// Disable isolation when building source distributions. /// Disable isolation when building source distributions.
/// ///
/// Assumes that build dependencies specified by PEP 518 are already installed. /// Assumes that build dependencies specified by [PEP 518](https://peps.python.org/pep-0518/)
/// are already installed.
#[option( #[option(
default = "false", default = "false",
value_type = "bool", value_type = "bool",
@ -826,14 +828,15 @@ pub struct PipOptions {
/// Use legacy `setuptools` behavior when building source distributions without a /// Use legacy `setuptools` behavior when building source distributions without a
/// `pyproject.toml`. /// `pyproject.toml`.
#[option( #[option(
default = "None", default = "false",
value_type = "bool", value_type = "bool",
example = r#" example = r#"
legacy-setup-py = true legacy-setup-py = true
"# "#
)] )]
pub legacy_setup_py: Option<bool>, pub legacy_setup_py: Option<bool>,
/// Settings to pass to the PEP 517 build backend, specified as `KEY=VALUE` pairs. /// Settings to pass to the [PEP 517](https://peps.python.org/pep-0517/) build backend,
/// specified as `KEY=VALUE` pairs.
#[option( #[option(
default = "{}", default = "{}",
value_type = "dict", value_type = "dict",
@ -876,7 +879,7 @@ pub struct PipOptions {
/// treated as a lower bound. For example, `--universal --python-version 3.7` would produce a /// treated as a lower bound. For example, `--universal --python-version 3.7` would produce a
/// universal resolution for Python 3.7 and later. /// universal resolution for Python 3.7 and later.
#[option( #[option(
default = "None", default = "false",
value_type = "bool", value_type = "bool",
example = r#" example = r#"
universal = true universal = true
@ -885,8 +888,8 @@ pub struct PipOptions {
pub universal: Option<bool>, pub universal: Option<bool>,
/// Limit candidate packages to those that were uploaded prior to the given date. /// Limit candidate packages to those that were uploaded prior to the given date.
/// ///
/// Accepts both RFC 3339 timestamps (e.g., `2006-12-02T02:07:43Z`) and UTC dates in the same /// Accepts both [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) timestamps (e.g.,
/// format (e.g., `2006-12-02`). /// `2006-12-02T02:07:43Z`) and UTC dates in the same format (e.g., `2006-12-02`).
#[option( #[option(
default = "None", default = "None",
value_type = "str", value_type = "str",
@ -928,7 +931,7 @@ pub struct PipOptions {
default = "false", default = "false",
value_type = "bool", value_type = "bool",
example = r#" example = r#"
emit-binary = true emit-build-options = true
"# "#
)] )]
pub emit_build_options: Option<bool>, pub emit_build_options: Option<bool>,

53
docs/settings.md
View File

@ -63,7 +63,8 @@ ignore errors.
#### [`config-settings`](#config-settings) {: #config-settings } #### [`config-settings`](#config-settings) {: #config-settings }
Settings to pass to the PEP 517 build backend, specified as `KEY=VALUE` pairs. Settings to pass to the [PEP 517](https://peps.python.org/pep-0517/) build backend,
specified as `KEY=VALUE` pairs.
**Default value**: `{}` **Default value**: `{}`
@ -90,8 +91,8 @@ Settings to pass to the PEP 517 build backend, specified as `KEY=VALUE` pairs.
Limit candidate packages to those that were uploaded prior to the given date. Limit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., `2006-12-02T02:07:43Z`) and UTC dates in the same Accepts both [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) timestamps (e.g.,
format (e.g., `2006-12-02`). `2006-12-02T02:07:43Z`) and UTC dates in the same format (e.g., `2006-12-02`).
**Default value**: `None` **Default value**: `None`
@ -118,8 +119,8 @@ format (e.g., `2006-12-02`).
Extra URLs of package indexes to use, in addition to `--index-url`. Extra URLs of package indexes to use, in addition to `--index-url`.
Accepts either a repository compliant with PEP 503 (the simple repository API), or a local Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/)
directory laid out in the same format. (the simple repository API), or a local directory laid out in the same format.
All indexes provided via this flag take priority over the index specified by All indexes provided via this flag take priority over the index specified by
[`index_url`](#index-url). When multiple indexes are provided, earlier values take priority. [`index_url`](#index-url). When multiple indexes are provided, earlier values take priority.
@ -218,8 +219,8 @@ same name to a secondary.
The URL of the Python package index (by default: <https://pypi.org/simple>). The URL of the Python package index (by default: <https://pypi.org/simple>).
Accepts either a repository compliant with PEP 503 (the simple repository API), or a local Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/)
directory laid out in the same format. (the simple repository API), or a local directory laid out in the same format.
The index provided by this setting is given lower priority than any indexes specified via The index provided by this setting is given lower priority than any indexes specified via
[`extra_index_url`](#extra-index-url). [`extra_index_url`](#extra-index-url).
@ -234,13 +235,13 @@ The index provided by this setting is given lower priority than any indexes spec
```toml ```toml
[tool.uv] [tool.uv]
index-url = "https://pypi.org/simple" index-url = "https://test.pypi.org/simple"
``` ```
=== "uv.toml" === "uv.toml"
```toml ```toml
index-url = "https://pypi.org/simple" index-url = "https://test.pypi.org/simple"
``` ```
--- ---
@ -626,13 +627,13 @@ Whether to automatically download Python when required.
```toml ```toml
[tool.uv] [tool.uv]
python-fetch = \"automatic\" python-fetch = "manual"
``` ```
=== "uv.toml" === "uv.toml"
```toml ```toml
python-fetch = \"automatic\" python-fetch = "manual"
``` ```
--- ---
@ -1049,7 +1050,8 @@ Defaults to the number of available CPU cores.
#### [`config-settings`](#pip_config-settings) {: #pip_config-settings } #### [`config-settings`](#pip_config-settings) {: #pip_config-settings }
<span id="config-settings"></span> <span id="config-settings"></span>
Settings to pass to the PEP 517 build backend, specified as `KEY=VALUE` pairs. Settings to pass to the [PEP 517](https://peps.python.org/pep-0517/) build backend,
specified as `KEY=VALUE` pairs.
**Default value**: `{}` **Default value**: `{}`
@ -1115,13 +1117,13 @@ Include `--no-binary` and `--only-binary` entries in the output file generated b
```toml ```toml
[tool.uv.pip] [tool.uv.pip]
emit-binary = true emit-build-options = true
``` ```
=== "uv.toml" === "uv.toml"
```toml ```toml
[pip] [pip]
emit-binary = true emit-build-options = true
``` ```
--- ---
@ -1241,8 +1243,8 @@ be correct.
Limit candidate packages to those that were uploaded prior to the given date. Limit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., `2006-12-02T02:07:43Z`) and UTC dates in the same Accepts both [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) timestamps (e.g.,
format (e.g., `2006-12-02`). `2006-12-02T02:07:43Z`) and UTC dates in the same format (e.g., `2006-12-02`).
**Default value**: `None` **Default value**: `None`
@ -1298,8 +1300,8 @@ Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.
Extra URLs of package indexes to use, in addition to `--index-url`. Extra URLs of package indexes to use, in addition to `--index-url`.
Accepts either a repository compliant with PEP 503 (the simple repository API), or a local Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/)
directory laid out in the same format. (the simple repository API), or a local directory laid out in the same format.
All indexes provided via this flag take priority over the index specified by All indexes provided via this flag take priority over the index specified by
[`index_url`](#index-url). When multiple indexes are provided, earlier values take priority. [`index_url`](#index-url). When multiple indexes are provided, earlier values take priority.
@ -1427,8 +1429,8 @@ same name to a secondary.
The URL of the Python package index (by default: <https://pypi.org/simple>). The URL of the Python package index (by default: <https://pypi.org/simple>).
Accepts either a repository compliant with PEP 503 (the simple repository API), or a local Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/)
directory laid out in the same format. (the simple repository API), or a local directory laid out in the same format.
The index provided by this setting is given lower priority than any indexes specified via The index provided by this setting is given lower priority than any indexes specified via
[`extra_index_url`](#extra-index-url). [`extra_index_url`](#extra-index-url).
@ -1443,13 +1445,13 @@ The index provided by this setting is given lower priority than any indexes spec
```toml ```toml
[tool.uv.pip] [tool.uv.pip]
index-url = "https://pypi.org/simple" index-url = "https://test.pypi.org/simple"
``` ```
=== "uv.toml" === "uv.toml"
```toml ```toml
[pip] [pip]
index-url = "https://pypi.org/simple" index-url = "https://test.pypi.org/simple"
``` ```
--- ---
@ -1489,7 +1491,7 @@ use the `keyring` CLI to handle authentication.
Use legacy `setuptools` behavior when building source distributions without a Use legacy `setuptools` behavior when building source distributions without a
`pyproject.toml`. `pyproject.toml`.
**Default value**: `None` **Default value**: `false`
**Type**: `bool` **Type**: `bool`
@ -1640,7 +1642,8 @@ Alias for `--only-binary :all:`.
Disable isolation when building source distributions. Disable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed. Assumes that build dependencies specified by [PEP 518](https://peps.python.org/pep-0518/)
are already installed.
**Default value**: `false` **Default value**: `false`
@ -2276,7 +2279,7 @@ In universal mode, the current Python version (or user-provided `--python-versio
treated as a lower bound. For example, `--universal --python-version 3.7` would produce a treated as a lower bound. For example, `--universal --python-version 3.7` would produce a
universal resolution for Python 3.7 and later. universal resolution for Python 3.7 and later.
**Default value**: `None` **Default value**: `false`
**Type**: `bool` **Type**: `bool`

18
uv.schema.json generated
View File

@ -19,7 +19,7 @@
] ]
}, },
"config-settings": { "config-settings": {
"description": "Settings to pass to the PEP 517 build backend, specified as `KEY=VALUE` pairs.", "description": "Settings to pass to the [PEP 517](https://peps.python.org/pep-0517/) build backend, specified as `KEY=VALUE` pairs.",
"anyOf": [ "anyOf": [
{ {
"$ref": "#/definitions/ConfigSettings" "$ref": "#/definitions/ConfigSettings"
@ -40,7 +40,7 @@
} }
}, },
"exclude-newer": { "exclude-newer": {
"description": "Limit candidate packages to those that were uploaded prior to the given date.\n\nAccepts both RFC 3339 timestamps (e.g., `2006-12-02T02:07:43Z`) and UTC dates in the same format (e.g., `2006-12-02`).", "description": "Limit candidate packages to those that were uploaded prior to the given date.\n\nAccepts both [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) timestamps (e.g., `2006-12-02T02:07:43Z`) and UTC dates in the same format (e.g., `2006-12-02`).",
"anyOf": [ "anyOf": [
{ {
"$ref": "#/definitions/ExcludeNewer" "$ref": "#/definitions/ExcludeNewer"
@ -51,7 +51,7 @@
] ]
}, },
"extra-index-url": { "extra-index-url": {
"description": "Extra URLs of package indexes to use, in addition to `--index-url`.\n\nAccepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.\n\nAll indexes provided via this flag take priority over the index specified by [`index_url`](#index-url). When multiple indexes are provided, earlier values take priority.\n\nTo control uv's resolution strategy when multiple indexes are present, see [`index_strategy`](#index-strategy).", "description": "Extra URLs of package indexes to use, in addition to `--index-url`.\n\nAccepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/) (the simple repository API), or a local directory laid out in the same format.\n\nAll indexes provided via this flag take priority over the index specified by [`index_url`](#index-url). When multiple indexes are provided, earlier values take priority.\n\nTo control uv's resolution strategy when multiple indexes are present, see [`index_strategy`](#index-strategy).",
"type": [ "type": [
"array", "array",
"null" "null"
@ -82,7 +82,7 @@
] ]
}, },
"index-url": { "index-url": {
"description": "The URL of the Python package index (by default: <https://pypi.org/simple>).\n\nAccepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.\n\nThe index provided by this setting is given lower priority than any indexes specified via [`extra_index_url`](#extra-index-url).", "description": "The URL of the Python package index (by default: <https://pypi.org/simple>).\n\nAccepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/) (the simple repository API), or a local directory laid out in the same format.\n\nThe index provided by this setting is given lower priority than any indexes specified via [`extra_index_url`](#extra-index-url).",
"anyOf": [ "anyOf": [
{ {
"$ref": "#/definitions/IndexUrl" "$ref": "#/definitions/IndexUrl"
@ -544,7 +544,7 @@
"minimum": 1.0 "minimum": 1.0
}, },
"config-settings": { "config-settings": {
"description": "Settings to pass to the PEP 517 build backend, specified as `KEY=VALUE` pairs.", "description": "Settings to pass to the [PEP 517](https://peps.python.org/pep-0517/) build backend, specified as `KEY=VALUE` pairs.",
"anyOf": [ "anyOf": [
{ {
"$ref": "#/definitions/ConfigSettings" "$ref": "#/definitions/ConfigSettings"
@ -597,7 +597,7 @@
] ]
}, },
"exclude-newer": { "exclude-newer": {
"description": "Limit candidate packages to those that were uploaded prior to the given date.\n\nAccepts both RFC 3339 timestamps (e.g., `2006-12-02T02:07:43Z`) and UTC dates in the same format (e.g., `2006-12-02`).", "description": "Limit candidate packages to those that were uploaded prior to the given date.\n\nAccepts both [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) timestamps (e.g., `2006-12-02T02:07:43Z`) and UTC dates in the same format (e.g., `2006-12-02`).",
"anyOf": [ "anyOf": [
{ {
"$ref": "#/definitions/ExcludeNewer" "$ref": "#/definitions/ExcludeNewer"
@ -618,7 +618,7 @@
} }
}, },
"extra-index-url": { "extra-index-url": {
"description": "Extra URLs of package indexes to use, in addition to `--index-url`.\n\nAccepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.\n\nAll indexes provided via this flag take priority over the index specified by [`index_url`](#index-url). When multiple indexes are provided, earlier values take priority.\n\nTo control uv's resolution strategy when multiple indexes are present, see [`index_strategy`](#index-strategy).", "description": "Extra URLs of package indexes to use, in addition to `--index-url`.\n\nAccepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/) (the simple repository API), or a local directory laid out in the same format.\n\nAll indexes provided via this flag take priority over the index specified by [`index_url`](#index-url). When multiple indexes are provided, earlier values take priority.\n\nTo control uv's resolution strategy when multiple indexes are present, see [`index_strategy`](#index-strategy).",
"type": [ "type": [
"array", "array",
"null" "null"
@ -656,7 +656,7 @@
] ]
}, },
"index-url": { "index-url": {
"description": "The URL of the Python package index (by default: <https://pypi.org/simple>).\n\nAccepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.\n\nThe index provided by this setting is given lower priority than any indexes specified via [`extra_index_url`](#extra-index-url).", "description": "The URL of the Python package index (by default: <https://pypi.org/simple>).\n\nAccepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/) (the simple repository API), or a local directory laid out in the same format.\n\nThe index provided by this setting is given lower priority than any indexes specified via [`extra_index_url`](#extra-index-url).",
"anyOf": [ "anyOf": [
{ {
"$ref": "#/definitions/IndexUrl" "$ref": "#/definitions/IndexUrl"
@ -720,7 +720,7 @@
] ]
}, },
"no-build-isolation": { "no-build-isolation": {
"description": "Disable isolation when building source distributions.\n\nAssumes that build dependencies specified by PEP 518 are already installed.", "description": "Disable isolation when building source distributions.\n\nAssumes that build dependencies specified by [PEP 518](https://peps.python.org/pep-0518/) are already installed.",
"type": [ "type": [
"boolean", "boolean",
"null" "null"