mirrors/uv
1
0
Fork 0
mirror of https://github.com/astral-sh/uv.git synced 2025-09-26 12:09:12 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Replace uv help python references in CLI documentation with links (#5871)

Browse source 
Following #5869, the documentation has some less-than-helpful
suggestions to use `uv help python` for details — we should link to the
`uv python` section instead.
This commit is contained in:
Zanie Blue 2024-08-07 12:21:09 -05:00 • committed by GitHub
parent fe2849af6a
commit c95bf76dfe
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 35 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

13
crates/uv-dev/src/generate_cli_reference.rs
View file

@ -13,6 +13,15 @@ use crate::ROOT_DIR;
use uv_cli::Cli; use uv_cli::Cli;
const REPLACEMENTS: &[(&str, &str)] = &[
// Replace suggestions to use `uv help python` with a link to the
// `uv python` section
(
"<code>uv help python</code>",
"<a href=\"#uv-python\">uv python</a>",
),
];
#[derive(clap::Args)] #[derive(clap::Args)]
pub(crate) struct Args { pub(crate) struct Args {
/// Write the generated output to stdout (rather than to `settings.md`). /// Write the generated output to stdout (rather than to `settings.md`).
@ -84,6 +93,10 @@ fn generate() -> String {
output.push_str("# CLI Reference\n\n"); output.push_str("# CLI Reference\n\n");
generate_command(&mut output, &uv, &mut parents); generate_command(&mut output, &uv, &mut parents);
for (value, replacement) in REPLACEMENTS {
output = output.replace(value, replacement);
}
output output
} }

44
docs/reference/cli.md
View file

@ -195,7 +195,7 @@ uv run [OPTIONS] <COMMAND>
<p>If the interpreter request is satisfied by a discovered environment, the environment will be used.</p> <p>If the interpreter request is satisfied by a discovered environment, the environment will be used.</p>
<p>See <code>uv help python</code> to view supported request formats.</p> <p>See <a href="#uv-python">uv python</a> to view supported request formats.</p>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -279,7 +279,7 @@ uv init [OPTIONS] [PATH]
</dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use to determine the minimum supported Python version.</p> </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use to determine the minimum supported Python version.</p>
<p>See <code>uv help python</code> to view supported request formats.</p> <p>See <a href="#uv-python">uv python</a> to view supported request formats.</p>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -464,7 +464,7 @@ uv add [OPTIONS] <REQUIREMENTS>...
</dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use for resolving and syncing.</p> </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use for resolving and syncing.</p>
<p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p> <p>See <a href="#uv-python">uv python</a> for details on Python discovery and supported request formats.</p>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -641,7 +641,7 @@ uv remove [OPTIONS] <REQUIREMENTS>...
</dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use for resolving and syncing.</p> </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use for resolving and syncing.</p>
<p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p> <p>See <a href="#uv-python">uv python</a> for details on Python discovery and supported request formats.</p>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -818,7 +818,7 @@ uv sync [OPTIONS]
<p>If a Python interpreter in a virtual environment is provided, the packages will not be synced to the given environment. The interpreter will be used to create a virtual environment in the project.</p> <p>If a Python interpreter in a virtual environment is provided, the packages will not be synced to the given environment. The interpreter will be used to create a virtual environment in the project.</p>
<p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p> <p>See <a href="#uv-python">uv python</a> for details on Python discovery and supported request formats.</p>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -989,7 +989,7 @@ uv lock [OPTIONS]
<p>The interpreter is also used as the fallback value for the minimum Python version if <code>requires-python</code> is not set.</p> <p>The interpreter is also used as the fallback value for the minimum Python version if <code>requires-python</code> is not set.</p>
<p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p> <p>See <a href="#uv-python">uv python</a> for details on Python discovery and supported request formats.</p>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -1210,7 +1210,7 @@ uv tree [OPTIONS]
<p>By default, the tree is filtered to match the platform as reported by the Python interpreter. Use <code>--universal</code> to display the tree for all platforms, or use <code>--python-version</code> or <code>--python-platform</code> to override a subset of markers.</p> <p>By default, the tree is filtered to match the platform as reported by the Python interpreter. Use <code>--universal</code> to display the tree for all platforms, or use <code>--python-version</code> or <code>--python-platform</code> to override a subset of markers.</p>
<p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p> <p>See <a href="#uv-python">uv python</a> for details on Python discovery and supported request formats.</p>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -1411,7 +1411,7 @@ uv tool run [OPTIONS] [COMMAND]
</dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use to build the run environment.</p> </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use to build the run environment.</p>
<p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p> <p>See <a href="#uv-python">uv python</a> for details on Python discovery and supported request formats.</p>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -1588,7 +1588,7 @@ uv tool install [OPTIONS] <PACKAGE>
</dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use to build the tool environment.</p> </dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use to build the tool environment.</p>
<p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p> <p>See <a href="#uv-python">uv python</a> for details on Python discovery and supported request formats.</p>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -2013,7 +2013,7 @@ uv python install [OPTIONS] [TARGETS]...
<p>If not provided, the requested Python version(s) will be read from the <code>.python-versions</code> or <code>.python-version</code> files. If neither file is present, uv will check if it has installed any Python versions. If not, it will install the latest stable version of Python.</p> <p>If not provided, the requested Python version(s) will be read from the <code>.python-versions</code> or <code>.python-version</code> files. If neither file is present, uv will check if it has installed any Python versions. If not, it will install the latest stable version of Python.</p>
<p>See <code>uv help python</code> to view supported request formats.</p> <p>See <a href="#uv-python">uv python</a> to view supported request formats.</p>
</dd></dl> </dd></dl>
@ -2079,7 +2079,7 @@ uv python find [OPTIONS] [REQUEST]
<dl class="cli-reference"><dt><code>REQUEST</code></dt><dd><p>The Python request.</p> <dl class="cli-reference"><dt><code>REQUEST</code></dt><dd><p>The Python request.</p>
<p>See <code>uv help python</code> to view supported request formats.</p> <p>See <a href="#uv-python">uv python</a> to view supported request formats.</p>
</dd></dl> </dd></dl>
@ -2147,7 +2147,7 @@ uv python pin [OPTIONS] [REQUEST]
<p>uv supports more formats than other tools that read <code>.python-version</code> files, i.e., <code>pyenv</code>. If compatibility with those tools is needed, only use version numbers instead of complex requests such as <code>cpython@3.10</code>.</p> <p>uv supports more formats than other tools that read <code>.python-version</code> files, i.e., <code>pyenv</code>. If compatibility with those tools is needed, only use version numbers instead of complex requests such as <code>cpython@3.10</code>.</p>
<p>See <code>uv help python</code> to view supported request formats.</p> <p>See <a href="#uv-python">uv python</a> to view supported request formats.</p>
</dd></dl> </dd></dl>
@ -2271,7 +2271,7 @@ uv python uninstall [OPTIONS] <TARGETS>...
<dl class="cli-reference"><dt><code>TARGETS</code></dt><dd><p>The Python version(s) to uninstall.</p> <dl class="cli-reference"><dt><code>TARGETS</code></dt><dd><p>The Python version(s) to uninstall.</p>
<p>See <code>uv help python</code> to view supported request formats.</p> <p>See <a href="#uv-python">uv python</a> to view supported request formats.</p>
</dd></dl> </dd></dl>
@ -2523,7 +2523,7 @@ uv pip compile [OPTIONS] <SRC_FILE>...
<p>The interpreter is also used to determine the default minimum Python version, unless <code>--python-version</code> is provided.</p> <p>The interpreter is also used to determine the default minimum Python version, unless <code>--python-version</code> is provided.</p>
<p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p> <p>See <a href="#uv-python">uv python</a> for details on Python discovery and supported request formats.</p>
</dd><dt><code>--no-binary</code> <i>no-binary</i></dt><dd><p>Don&#8217;t install pre-built wheels.</p> </dd><dt><code>--no-binary</code> <i>no-binary</i></dt><dd><p>Don&#8217;t install pre-built wheels.</p>
@ -2739,7 +2739,7 @@ uv pip sync [OPTIONS] <SRC_FILE>...
<p>By default, syncing requires a virtual environment. An path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.</p> <p>By default, syncing requires a virtual environment. An path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.</p>
<p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p> <p>See <a href="#uv-python">uv python</a> for details on Python discovery and supported request formats.</p>
</dd><dt><code>--target</code> <i>target</i></dt><dd><p>Install packages into the specified directory, rather than into the virtual or system Python environment. The packages will be installed at the top-level of the directory</p> </dd><dt><code>--target</code> <i>target</i></dt><dd><p>Install packages into the specified directory, rather than into the virtual or system Python environment. The packages will be installed at the top-level of the directory</p>
@ -3001,7 +3001,7 @@ uv pip install [OPTIONS] <PACKAGE|--requirement <REQUIREMENT>|--editable <EDITAB
<p>By default, installation requires a virtual environment. An path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.</p> <p>By default, installation requires a virtual environment. An path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.</p>
<p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p> <p>See <a href="#uv-python">uv python</a> for details on Python discovery and supported request formats.</p>
</dd><dt><code>--target</code> <i>target</i></dt><dd><p>Install packages into the specified directory, rather than into the virtual or system Python environment. The packages will be installed at the top-level of the directory</p> </dd><dt><code>--target</code> <i>target</i></dt><dd><p>Install packages into the specified directory, rather than into the virtual or system Python environment. The packages will be installed at the top-level of the directory</p>
@ -3136,7 +3136,7 @@ uv pip uninstall [OPTIONS] <PACKAGE|--requirement <REQUIREMENT>>
<p>By default, uninstallation requires a virtual environment. An path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.</p> <p>By default, uninstallation requires a virtual environment. An path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.</p>
<p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p> <p>See <a href="#uv-python">uv python</a> for details on Python discovery and supported request formats.</p>
</dd><dt><code>--keyring-provider</code> <i>keyring-provider</i></dt><dd><p>Attempt to use <code>keyring</code> for authentication for remote requirements files.</p> </dd><dt><code>--keyring-provider</code> <i>keyring-provider</i></dt><dd><p>Attempt to use <code>keyring</code> for authentication for remote requirements files.</p>
@ -3217,7 +3217,7 @@ uv pip freeze [OPTIONS]
<p>By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.</p> <p>By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.</p>
<p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p> <p>See <a href="#uv-python">uv python</a> for details on Python discovery and supported request formats.</p>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -3295,7 +3295,7 @@ uv pip list [OPTIONS]
<p>By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.</p> <p>By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.</p>
<p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p> <p>See <a href="#uv-python">uv python</a> for details on Python discovery and supported request formats.</p>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -3365,7 +3365,7 @@ uv pip show [OPTIONS] [PACKAGE]...
<p>By default, uv looks for packages in a virtual environment but will look for packages in a system Python environment if no virtual environment is found.</p> <p>By default, uv looks for packages in a virtual environment but will look for packages in a system Python environment if no virtual environment is found.</p>
<p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p> <p>See <a href="#uv-python">uv python</a> for details on Python discovery and supported request formats.</p>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -3436,7 +3436,7 @@ uv pip tree [OPTIONS]
<p>By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.</p> <p>By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.</p>
<p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p> <p>See <a href="#uv-python">uv python</a> for details on Python discovery and supported request formats.</p>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>
@ -3500,7 +3500,7 @@ uv pip check [OPTIONS]
<p>By default, uv checks packages in a virtual environment but will check packages in a system Python environment if no virtual environment is found.</p> <p>By default, uv checks packages in a virtual environment but will check packages in a system Python environment if no virtual environment is found.</p>
<p>See <code>uv help python</code> for details on Python discovery and supported request formats.</p> <p>See <a href="#uv-python">uv python</a> for details on Python discovery and supported request formats.</p>
</dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p> </dd><dt><code>--cache-dir</code> <i>cache-dir</i></dt><dd><p>Path to the cache directory.</p>