Skip to content

Commit

Permalink
Improve documentation for uv init CLI (#5862)
Browse files Browse the repository at this point in the history
  • Loading branch information
@zanieb
zanieb authored Aug 7, 2024
1 parent f29bdcb commit 32d8ea1
Show file tree
Hide file tree
Showing 2 changed files with 60 additions and 48 deletions.
62 changes: 39 additions & 23 deletions crates/uv-cli/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -465,6 +465,19 @@ pub enum ProjectCommand {
)]
Run(RunArgs),
/// Create a new project (experimental).
///
/// Follows the `pyproject.toml` specification.
///
/// If a `pyproject.toml` already exists at the target, uv will exit with an
/// error.
///
/// If a `pyproject.toml` is found in any of the parent directories of the
/// target path, the project will be added as a workspace member of
/// the parent.
///
/// Some project state is not created until needed, e.g., the project
/// virtual environment (`.venv`) and lockfile (`uv.lock`) are lazily
/// created during the first sync.
Init(InitArgs),
/// Add dependencies to the project (experimental).
#[command(
Expand Down Expand Up @@ -1939,37 +1952,46 @@ impl ExternalCommand {
#[derive(Args)]
#[allow(clippy::struct_excessive_bools)]
pub struct InitArgs {
/// The path of the project.
/// The path to use for the project.
///
/// Defaults to the current working directory. Accepts relative and absolute
/// paths.
///
/// If a `pyproject.toml` is found in any of the parent directories of the
/// target path, the project will be added as a workspace member of the
/// parent, unless `--no-workspace` is provided.
pub path: Option<String>,

/// The name of the project, defaults to the name of the directory.
/// The name of the project.
///
/// Defaults to the name of the directory.
#[arg(long)]
pub name: Option<PackageName>,

/// Create a virtual workspace instead of a project.
///
/// A virtual workspace does not define project dependencies and cannot be
/// published. Instead, workspace members declare project dependencies.
/// Development dependencies may still be declared.
#[arg(long)]
pub r#virtual: bool,

/// Do not create a `README.md` file.
#[arg(long)]
pub no_readme: bool,

/// Avoid discovering the workspace in the current directory or any parent directory. Instead,
/// create a standalone project.
/// Avoid discovering a workspace.
///
/// Instead, create a standalone project.
///
/// By default, uv searches for workspaces in the current directory or any
/// parent directory.
#[arg(long, alias = "no_project")]
pub no_workspace: bool,

/// The Python interpreter to use to determine the minimum supported Python version.
///
/// By default, uv uses the virtual environment in the current working directory or any parent
/// directory, falling back to searching for a Python executable in `PATH`. The `--python`
/// option allows you to specify a different interpreter.
///
/// Supported formats:
/// - `3.10` looks for an installed Python 3.10 using `py --list-paths` on Windows, or
/// `python3.10` on Linux and macOS.
/// - `python3.10` or `python.exe` looks for a binary with the given name in `PATH`.
/// - `/home/ferris/.local/bin/python3.10` uses the exact Python at the given path.
/// See `uv help python` to view supported request formats.
#[arg(
long,
short,
Expand Down Expand Up @@ -2101,18 +2123,12 @@ pub struct RunArgs {
#[arg(long, alias = "no_workspace", conflicts_with = "package")]
pub no_project: bool,

/// The Python interpreter to use to build the run environment.
///
/// By default, uv uses the virtual environment in the current working directory or any parent
/// directory, falling back to searching for a Python executable in `PATH`. The `--python`
/// option allows you to specify a different interpreter.
/// The Python interpreter to use for the run environment.
///
/// Supported formats:
/// If the interpreter request is satisfied by a discovered environment, the
/// environment will be used.
///
/// - `3.10` looks for an installed Python 3.10 using `py --list-paths` on Windows, or
/// `python3.10` on Linux and macOS.
/// - `python3.10` or `python.exe` looks for a binary with the given name in `PATH`.
/// - `/home/ferris/.local/bin/python3.10` uses the exact Python at the given path.
/// See `uv help python` to view supported request formats.
#[arg(
long,
short,
Expand Down
46 changes: 21 additions & 25 deletions docs/reference/cli.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -191,19 +191,11 @@ uv run [OPTIONS] <COMMAND>

<p>If not in a workspace, or if the workspace member does not exist, uv will exit with an error.</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>By default, uv uses the virtual environment in the current working directory or any parent directory, falling back to searching for a Python executable in <code>PATH</code>. The <code>--python</code> option allows you to specify a different interpreter.</p>

<p>Supported formats:</p>
</dd><dt><code>--python</code>, <code>-p</code> <i>python</i></dt><dd><p>The Python interpreter to use for the run environment.</p>

<ul>
<li><code>3.10</code> looks for an installed Python 3.10 using <code>py --list-paths</code> on Windows, or <code>python3.10</code> on Linux and macOS.</li>
<p>If the interpreter request is satisfied by a discovered environment, the environment will be used.</p>

<li><code>python3.10</code> or <code>python.exe</code> looks for a binary with the given name in <code>PATH</code>.</li>

<li><code>/home/ferris/.local/bin/python3.10</code> uses the exact Python at the given path.</li>
</ul>
<p>See <code>uv help python</code> 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 @@ -253,7 +245,15 @@ uv run [OPTIONS] <COMMAND>

## uv init

Create a new project (experimental)
Create a new project (experimental).

Follows the `pyproject.toml` specification.

If a `pyproject.toml` already exists at the target, uv will exit with an error.

If a `pyproject.toml` is found in any of the parent directories of the target path, the project will be added as a workspace member of the parent.

Some project state is not created until needed, e.g., the project virtual environment (`.venv`) and lockfile (`uv.lock`) are lazily created during the first sync.

<h3 class="cli-reference">Usage</h3>

Expand All @@ -263,27 +263,23 @@ uv init [OPTIONS] [PATH]

<h3 class="cli-reference">Arguments</h3>

<dl class="cli-reference"><dt><code>PATH</code></dt><dd><p>The path of the project</p>
<dl class="cli-reference"><dt><code>PATH</code></dt><dd><p>The path to use for the project.</p>

</dd></dl>

<h3 class="cli-reference">Options</h3>
<p>Defaults to the current working directory. Accepts relative and absolute paths.</p>

<dl class="cli-reference"><dt><code>--name</code> <i>name</i></dt><dd><p>The name of the project, defaults to the name of the directory</p>
<p>If a <code>pyproject.toml</code> is found in any of the parent directories of the target path, the project will be added as a workspace member of the parent, unless <code>--no-workspace</code> is provided.</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>
</dd></dl>

<p>By default, uv uses the virtual environment in the current working directory or any parent directory, falling back to searching for a Python executable in <code>PATH</code>. The <code>--python</code> option allows you to specify a different interpreter.</p>
<h3 class="cli-reference">Options</h3>

<p>Supported formats:</p>
<dl class="cli-reference"><dt><code>--name</code> <i>name</i></dt><dd><p>The name of the project.</p>

<ul>
<li><code>3.10</code> looks for an installed Python 3.10 using <code>py --list-paths</code> on Windows, or <code>python3.10</code> on Linux and macOS.</li>
<p>Defaults to the name of the directory.</p>

<li><code>python3.10</code> or <code>python.exe</code> looks for a binary with the given name in <code>PATH</code>.</li>
</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>

<li><code>/home/ferris/.local/bin/python3.10</code> uses the exact Python at the given path.</li>
</ul>
<p>See <code>uv help python</code> 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

0 comments on commit 32d8ea1

Please sign in to comment.