From 400e57b78d47e70854a7c1f240eae8065fb64f36 Mon Sep 17 00:00:00 2001
From: Juliya Smith <jules@apeworx.io>
Date: Tue, 25 Jul 2023 09:49:44 -0500
Subject: [PATCH] docs: logging guide

---
 docs/index.md                   |  1 +
 docs/userguides/dependencies.md |  2 +-
 docs/userguides/logging.md      | 49 +++++++++++++++++++++++++++++++++
 3 files changed, 51 insertions(+), 1 deletion(-)
 create mode 100644 docs/userguides/logging.md

diff --git a/docs/index.md b/docs/index.md
index 37dce95258..6154bff3e5 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -23,6 +23,7 @@
    userguides/testing
    userguides/scripts
    userguides/publishing
+   userguides/logging
 ```
 
 ```{eval-rst}
diff --git a/docs/userguides/dependencies.md b/docs/userguides/dependencies.md
index 4873faf2ef..7d9dfebec5 100644
--- a/docs/userguides/dependencies.md
+++ b/docs/userguides/dependencies.md
@@ -74,7 +74,7 @@ Then, add the following to your config so that Ape can find the dependency:
 ```yaml
 dependencies:
   - name: MyDependency
-    npm: @myorg/mydependency
+    npm: "@myorg/mydependency"
     version: v1.3.0
 ```
 
diff --git a/docs/userguides/logging.md b/docs/userguides/logging.md
new file mode 100644
index 0000000000..140a76e538
--- /dev/null
+++ b/docs/userguides/logging.md
@@ -0,0 +1,49 @@
+# Logging
+
+Ape provides a logger and uses it to show messages throughout the execution of its modules.
+Every CLI command comes with the logger in Ape, even custom user scripts (unless they change the behavior of `--verbosity`).
+
+The following log levels are available with Ape:
+
+| Log Level       | Numeric Value | Purpose                         | Color  |
+|-----------------|---------------|---------------------------------|--------|
+| DEBUG           | 10            | Debug stuff                     | Blue   |
+| INFO            | 20            | General information             | Blue   |
+| SUCCESS         | 21            | To mark a successful operation  | Green  |
+| WARNING         | 30            | Indicates a potential issue     | Yellow |
+| ERROR           | 40            | An error occurred               | Red    |
+
+**NOTE**: `SUCCESS` is a non-standard verbosity level custom to the framework.
+It is shown during `INFO` but not shown if set to `WARNING` or above.
+
+## CLI Logging
+
+If you are running into issues and wish to see more information logged, you likely want to run your command with `--verbosity DEBUG` or `-v debug`:
+
+```bash
+ape --verbosity DEBUG my_cmd  # long form
+ape -v debug my_cmd           # short form
+```
+
+This will output HTTP requests and anything else with a `DEBUG` logging verbosity in Ape.
+
+Alternatively, you may wish to log less and show important logs, such as `ERROR` logs.
+To do this, use the `ERROR` verbosity:
+
+```bash
+ape my_cmd -v ERROR 
+```
+
+*NOTE*: You can put the verbosity flag anywhere in your CLI command for _most_ commands.
+
+## Python Logging
+
+You can also import and use the logger in your own Python scripts or commands:
+
+```python
+from ape.logging import logger, LogLevel
+
+def main():
+    logger.info("You have entered `main()`.")
+    logger.set_level(LogLevel.WARNING)
+```