mirror of
https://github.com/astral-sh/uv.git
synced 2025-11-01 12:24:15 +00:00
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
GitHub
parent
b1a350cb9f
commit
f2e2825d1b
4 changed files with 72 additions and 56 deletions
|
|
@ -127,11 +127,21 @@ To preview any changes to the documentation locally:
|
|||
|
||||
# For contributors.
|
||||
uv pip install -r docs/requirements.txt
|
||||
|
||||
|
||||
# Or, for members of the Astral org, which has access to MkDocs Insiders via sponsorship.
|
||||
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:
|
||||
|
||||
```shell
|
||||
|
|
|
|||
|
|
@ -129,7 +129,7 @@ pub struct GlobalOptions {
|
|||
default = "\"automatic\"",
|
||||
value_type = "str",
|
||||
example = r#"
|
||||
python-fetch = \"automatic\"
|
||||
python-fetch = "manual"
|
||||
"#,
|
||||
possible_values = true
|
||||
)]
|
||||
|
|
@ -194,8 +194,8 @@ pub struct ResolverOptions {
|
|||
pub struct ResolverInstallerOptions {
|
||||
/// 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
|
||||
/// directory laid out in the same format.
|
||||
/// Accepts 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.
|
||||
///
|
||||
/// The index provided by this setting is given lower priority than any indexes specified via
|
||||
/// [`extra_index_url`](#extra-index-url).
|
||||
|
|
@ -203,14 +203,14 @@ pub struct ResolverInstallerOptions {
|
|||
default = "\"https://pypi.org/simple\"",
|
||||
value_type = "str",
|
||||
example = r#"
|
||||
index-url = "https://pypi.org/simple"
|
||||
index-url = "https://test.pypi.org/simple"
|
||||
"#
|
||||
)]
|
||||
pub index_url: Option<IndexUrl>,
|
||||
/// 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
|
||||
/// directory laid out in the same format.
|
||||
/// Accepts 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.
|
||||
///
|
||||
/// 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.
|
||||
|
|
@ -305,7 +305,8 @@ pub struct ResolverInstallerOptions {
|
|||
possible_values = true
|
||||
)]
|
||||
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(
|
||||
default = "{}",
|
||||
value_type = "dict",
|
||||
|
|
@ -316,8 +317,8 @@ pub struct ResolverInstallerOptions {
|
|||
pub config_settings: Option<ConfigSettings>,
|
||||
/// 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
|
||||
/// format (e.g., `2006-12-02`).
|
||||
/// Accepts 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`).
|
||||
#[option(
|
||||
default = "None",
|
||||
value_type = "str",
|
||||
|
|
@ -527,8 +528,8 @@ pub struct PipOptions {
|
|||
pub prefix: Option<PathBuf>,
|
||||
/// 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
|
||||
/// directory laid out in the same format.
|
||||
/// Accepts 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.
|
||||
///
|
||||
/// The index provided by this setting is given lower priority than any indexes specified via
|
||||
/// [`extra_index_url`](#extra-index-url).
|
||||
|
|
@ -536,14 +537,14 @@ pub struct PipOptions {
|
|||
default = "\"https://pypi.org/simple\"",
|
||||
value_type = "str",
|
||||
example = r#"
|
||||
index-url = "https://pypi.org/simple"
|
||||
index-url = "https://test.pypi.org/simple"
|
||||
"#
|
||||
)]
|
||||
pub index_url: Option<IndexUrl>,
|
||||
/// 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
|
||||
/// directory laid out in the same format.
|
||||
/// Accepts 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.
|
||||
///
|
||||
/// 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.
|
||||
|
|
@ -659,7 +660,8 @@ pub struct PipOptions {
|
|||
pub only_binary: Option<Vec<PackageNameSpecifier>>,
|
||||
/// 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(
|
||||
default = "false",
|
||||
value_type = "bool",
|
||||
|
|
@ -826,14 +828,15 @@ pub struct PipOptions {
|
|||
/// Use legacy `setuptools` behavior when building source distributions without a
|
||||
/// `pyproject.toml`.
|
||||
#[option(
|
||||
default = "None",
|
||||
default = "false",
|
||||
value_type = "bool",
|
||||
example = r#"
|
||||
legacy-setup-py = true
|
||||
"#
|
||||
)]
|
||||
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(
|
||||
default = "{}",
|
||||
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
|
||||
/// universal resolution for Python 3.7 and later.
|
||||
#[option(
|
||||
default = "None",
|
||||
default = "false",
|
||||
value_type = "bool",
|
||||
example = r#"
|
||||
universal = true
|
||||
|
|
@ -885,8 +888,8 @@ pub struct PipOptions {
|
|||
pub universal: Option<bool>,
|
||||
/// 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
|
||||
/// format (e.g., `2006-12-02`).
|
||||
/// Accepts 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`).
|
||||
#[option(
|
||||
default = "None",
|
||||
value_type = "str",
|
||||
|
|
@ -928,7 +931,7 @@ pub struct PipOptions {
|
|||
default = "false",
|
||||
value_type = "bool",
|
||||
example = r#"
|
||||
emit-binary = true
|
||||
emit-build-options = true
|
||||
"#
|
||||
)]
|
||||
pub emit_build_options: Option<bool>,
|
||||
|
|
|
|||
|
|
@ -63,7 +63,8 @@ ignore errors.
|
|||
|
||||
#### [`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**: `{}`
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
Accepts both RFC 3339 timestamps (e.g., `2006-12-02T02:07:43Z`) and UTC dates in the same
|
||||
format (e.g., `2006-12-02`).
|
||||
Accepts 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`).
|
||||
|
||||
**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`.
|
||||
|
||||
Accepts either a repository compliant with PEP 503 (the simple repository API), or a local
|
||||
directory laid out in the same format.
|
||||
Accepts 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.
|
||||
|
||||
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.
|
||||
|
|
@ -218,8 +219,8 @@ same name to a secondary.
|
|||
|
||||
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
|
||||
directory laid out in the same format.
|
||||
Accepts 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.
|
||||
|
||||
The index provided by this setting is given lower priority than any indexes specified via
|
||||
[`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
|
||||
[tool.uv]
|
||||
index-url = "https://pypi.org/simple"
|
||||
index-url = "https://test.pypi.org/simple"
|
||||
```
|
||||
=== "uv.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
|
||||
[tool.uv]
|
||||
python-fetch = \"automatic\"
|
||||
python-fetch = "manual"
|
||||
```
|
||||
=== "uv.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 }
|
||||
<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**: `{}`
|
||||
|
||||
|
|
@ -1115,13 +1117,13 @@ Include `--no-binary` and `--only-binary` entries in the output file generated b
|
|||
|
||||
```toml
|
||||
[tool.uv.pip]
|
||||
emit-binary = true
|
||||
emit-build-options = true
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
[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.
|
||||
|
||||
Accepts both RFC 3339 timestamps (e.g., `2006-12-02T02:07:43Z`) and UTC dates in the same
|
||||
format (e.g., `2006-12-02`).
|
||||
Accepts 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`).
|
||||
|
||||
**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`.
|
||||
|
||||
Accepts either a repository compliant with PEP 503 (the simple repository API), or a local
|
||||
directory laid out in the same format.
|
||||
Accepts 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.
|
||||
|
||||
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.
|
||||
|
|
@ -1427,8 +1429,8 @@ same name to a secondary.
|
|||
|
||||
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
|
||||
directory laid out in the same format.
|
||||
Accepts 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.
|
||||
|
||||
The index provided by this setting is given lower priority than any indexes specified via
|
||||
[`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
|
||||
[tool.uv.pip]
|
||||
index-url = "https://pypi.org/simple"
|
||||
index-url = "https://test.pypi.org/simple"
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
[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
|
||||
`pyproject.toml`.
|
||||
|
||||
**Default value**: `None`
|
||||
**Default value**: `false`
|
||||
|
||||
**Type**: `bool`
|
||||
|
||||
|
|
@ -1640,7 +1642,8 @@ Alias for `--only-binary :all:`.
|
|||
|
||||
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`
|
||||
|
||||
|
|
@ -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
|
||||
universal resolution for Python 3.7 and later.
|
||||
|
||||
**Default value**: `None`
|
||||
**Default value**: `false`
|
||||
|
||||
**Type**: `bool`
|
||||
|
||||
|
|
|
|||
18
uv.schema.json
generated
18
uv.schema.json
generated
|
|
@ -19,7 +19,7 @@
|
|||
]
|
||||
},
|
||||
"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": [
|
||||
{
|
||||
"$ref": "#/definitions/ConfigSettings"
|
||||
|
|
@ -40,7 +40,7 @@
|
|||
}
|
||||
},
|
||||
"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": [
|
||||
{
|
||||
"$ref": "#/definitions/ExcludeNewer"
|
||||
|
|
@ -51,7 +51,7 @@
|
|||
]
|
||||
},
|
||||
"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": [
|
||||
"array",
|
||||
"null"
|
||||
|
|
@ -82,7 +82,7 @@
|
|||
]
|
||||
},
|
||||
"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": [
|
||||
{
|
||||
"$ref": "#/definitions/IndexUrl"
|
||||
|
|
@ -544,7 +544,7 @@
|
|||
"minimum": 1.0
|
||||
},
|
||||
"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": [
|
||||
{
|
||||
"$ref": "#/definitions/ConfigSettings"
|
||||
|
|
@ -597,7 +597,7 @@
|
|||
]
|
||||
},
|
||||
"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": [
|
||||
{
|
||||
"$ref": "#/definitions/ExcludeNewer"
|
||||
|
|
@ -618,7 +618,7 @@
|
|||
}
|
||||
},
|
||||
"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": [
|
||||
"array",
|
||||
"null"
|
||||
|
|
@ -656,7 +656,7 @@
|
|||
]
|
||||
},
|
||||
"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": [
|
||||
{
|
||||
"$ref": "#/definitions/IndexUrl"
|
||||
|
|
@ -720,7 +720,7 @@
|
|||
]
|
||||
},
|
||||
"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": [
|
||||
"boolean",
|
||||
"null"
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue