From 4fb68682f544d9a46330985450874cd161f8def4 Mon Sep 17 00:00:00 2001
From: Miles Johnson <mileswjohnson@gmail.com>
Date: Mon, 28 Aug 2023 11:07:29 -0700
Subject: [PATCH] docs: Add espm new docs.

---
 crates/cli/src/commands/new.rs | 10 ++++++++--
 docs/README.md                 |  3 ++-
 docs/commands/new.md           | 21 +++++++++++++++++++++
 docs/package.md                | 10 +++++++++-
 4 files changed, 40 insertions(+), 4 deletions(-)
 create mode 100644 docs/commands/new.md

diff --git a/crates/cli/src/commands/new.rs b/crates/cli/src/commands/new.rs
index 3d93e86..6d2e498 100644
--- a/crates/cli/src/commands/new.rs
+++ b/crates/cli/src/commands/new.rs
@@ -24,10 +24,16 @@ pub struct NewArgs {
     #[arg(long, short = 'n', help = "Name of package.")]
     pub name: Option<PackageName>,
 
-    #[arg(long, help = "Path to create the package in.")]
+    #[arg(
+        long,
+        help = "Path to create the package in, relative from working directory."
+    )]
     pub to: Option<String>,
 
-    #[arg(long, help = "Skip all prompts and use default values.")]
+    #[arg(
+        long,
+        help = "Skip all interactive prompts and use default or provided values"
+    )]
     pub yes: bool,
 }
 
diff --git a/docs/README.md b/docs/README.md
index bbcdced..d11424c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -13,4 +13,5 @@
 
 ## Commands
 
-- [`espm build`](./commands/build.md) - Builds a package.
+- [`espm new`](./commands/new.md) - Create a package.
+- [`espm build`](./commands/build.md) - Build a package.
diff --git a/docs/commands/new.md b/docs/commands/new.md
new file mode 100644
index 0000000..1a7d652
--- /dev/null
+++ b/docs/commands/new.md
@@ -0,0 +1,21 @@
+# `new`
+
+The `espm new` command can be used to create and scaffold a new package. It will prompt you for a
+package name, description, and other metadata, and will create a package with the necessary files,
+like [`esp.toml`](../esp-toml.md).
+
+```shell
+espm new
+espm new --name namespace/package --yes
+```
+
+> Prompt values can be autopopulated by passing options on the command line.
+
+## Options
+
+- `--to` - Destination to create the package in, relative from the current working directory.
+  Defaults to ".".
+- `--name`, `-n` - Name of package.
+- `--description`, `-d` - Description of package.
+- `--keyword`, `-k` - List of keywords about the package. Can be provided multiple times.
+- `--yes` - Skip all interactive prompts and use default or provided values.
diff --git a/docs/package.md b/docs/package.md
index f32e7ac..2921424 100644
--- a/docs/package.md
+++ b/docs/package.md
@@ -81,7 +81,15 @@ in [TOML](https://toml.io/en/) and configures metadata about the package, like i
 description, as well as dependencies (other packages) it requires, and also denotes the root of the
 package.
 
-Begin by creating the `esp.toml` file in your project, and insert the following initial content:
+To easily create a package, run the [`espm new`](./commands/new.md) command and answer all the
+prompts.
+
+```shell
+espm new
+```
+
+Otherwise, if you'd prefer to create a package manually, begin by creating the `esp.toml` file in
+your project, and insert the following initial content:
 
 ```toml
 [package]