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.
astral-sh · Jul 19, 2024 · f2e2825 · f2e2825
1 parent b1a350c
commit f2e2825
Show file tree

Hide file tree

Showing 4 changed files with 72 additions and 56 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -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

diff --git a/crates/uv-settings/src/settings.rs b/crates/uv-settings/src/settings.rs
@@ -129,7 +129,7 @@ pub struct GlobalOptions {
         default = "\"automatic\"",
         value_type = "str",
         example = r#"
-            python-fetch = \"automatic\"
+            python-fetch = "manual"
         "#,
         possible_values = true
     )]
@@ -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.
@@ -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,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.
@@ -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>,

diff --git a/docs/settings.md b/docs/settings.md
@@ -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`