Skip to content

Commit

Permalink
Replace uv help python references in CLI documentation with links (#…
Browse files Browse the repository at this point in the history 
…5871)

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.
  • Loading branch information
@zanieb
zanieb authored Aug 7, 2024
1 parent fe2849a commit c95bf76
Show file tree
Hide file tree
Showing 2 changed files with 35 additions and 22 deletions.
13 changes: 13 additions & 0 deletions crates/uv-dev/src/generate_cli_reference.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,15 @@ use crate::ROOT_DIR;

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)]
pub(crate) struct Args {
/// Write the generated output to stdout (rather than to `settings.md`).
Expand Down Expand Up @@ -84,6 +93,10 @@ fn generate() -> String {
output.push_str("# CLI Reference\n\n");
generate_command(&mut output, &uv, &mut parents);

for (value, replacement) in REPLACEMENTS {
output = output.replace(value, replacement);
}

output
}

Expand Down
44 changes: 22 additions & 22 deletions docs/reference/cli.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>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>

Expand Down Expand Up @@ -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>

<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>

Expand Down Expand Up @@ -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>

<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>

Expand Down Expand Up @@ -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>

<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>

Expand Down Expand Up @@ -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>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>

Expand Down Expand Up @@ -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>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>

Expand Down Expand Up @@ -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>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>

Expand Down Expand Up @@ -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>

<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>

Expand Down Expand Up @@ -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>

<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>

Expand Down Expand Up @@ -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>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>

Expand Down Expand Up @@ -2079,7 +2079,7 @@ uv python find [OPTIONS] [REQUEST]

<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>

Expand Down Expand Up @@ -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>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>

Expand Down Expand Up @@ -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>

<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>

Expand Down Expand Up @@ -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>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>

Expand Down Expand Up @@ -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>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>

Expand Down Expand Up @@ -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>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>

Expand Down Expand Up @@ -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>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>

Expand Down Expand Up @@ -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>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>

Expand Down Expand Up @@ -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>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>

Expand Down Expand Up @@ -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>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>

Expand Down Expand Up @@ -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>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>

Expand Down Expand Up @@ -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>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>

Expand Down

0 comments on commit c95bf76

Please sign in to comment.