Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 4 commits into from
Jul 19, 2024
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e818bf5
docs(settings): fix some defaults and examples
mkniewallner Jul 18, 2024
0af970e
docs(settings): add links to PEPs and RFCs
mkniewallner Jul 18, 2024
b7f7a53
chore: run `cargo dev generate-all`
mkniewallner Jul 18, 2024
210331c
docs(contributing): mention need to enable venv
mkniewallner Jul 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The bullet point numbers below this are now off

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In markdown, it doesn't matter which number you use for ordered lists, as using "1" for multiple consecutive items will still generate a numerically ordered list: https://www.markdownguide.org/basic-syntax/#ordered-lists

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interesting, didn't know about that feature!


```shell
Expand Down
45 changes: 24 additions & 21 deletions crates/uv-settings/src/settings.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,7 @@ pub struct GlobalOptions {
default = "\"automatic\"",
value_type = "str",
example = r#"
python-fetch = \"automatic\"
python-fetch = "manual"
"#,
possible_values = true
)]
Expand Down Expand Up @@ -194,23 +194,23 @@ 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).
#[option(
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.
Expand Down Expand Up @@ -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",
Expand All @@ -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",
Expand Down Expand Up @@ -527,23 +528,23 @@ 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).
#[option(
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.
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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
Expand All @@ -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",
Expand Down Expand Up @@ -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>,
Expand Down
53 changes: 28 additions & 25 deletions docs/settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**: `{}`

Expand All @@ -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`

Expand All @@ -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.
Expand Down Expand Up @@ -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).
Expand All @@ -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"
```

---
Expand Down Expand Up @@ -625,13 +626,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"
```

---
Expand Down Expand Up @@ -1048,7 +1049,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**: `{}`

Expand Down Expand Up @@ -1114,13 +1116,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
```

---
Expand Down Expand Up @@ -1240,8 +1242,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`

Expand Down Expand Up @@ -1297,8 +1299,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.
Expand Down Expand Up @@ -1426,8 +1428,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).
Expand All @@ -1442,13 +1444,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"
```

---
Expand Down Expand Up @@ -1488,7 +1490,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`

Expand Down Expand Up @@ -1638,7 +1640,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`

Expand Down Expand Up @@ -2274,7 +2277,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`

Expand Down
Loading
Loading