Update documentation

Author: zph

.config/README.md.template

@@ -31,7 +31,7 @@ runbook run runbook-name.ipynb
 
 # Background
 
-### What is a Runbook?
+## What is a Runbook?
 A runbook is an executable document that combines:
 - Clear markdown documentation
 - Runnable code blocks
@@ -40,13 +40,13 @@ A runbook is an executable document that combines:
 
 It's ideal for operations like encoding your Disaster Recovery Operations, spinning up a new cluster, or restoring from snapshots.
 
-### When Should You Use This?
+## When Should You Use This?
 - ✅ When you need **semi-automated tools** with audit trails and safety checks
 - ✅ When you want **rapid iteration** on operational procedures with built-in rollback steps
 - ✅ When you need something more powerful than shell scripts but don't want to build a full application
 - ✅ When you want to make complex operations both **safe and repeatable**
 
-### Runbook Best Practices
+## Runbook Best Practices
 1. Structure your runbooks with:
    - Clear purpose and summary
    - Step-by-step descriptions
@@ -72,7 +72,7 @@ It's ideal for operations like encoding your Disaster Recovery Operations, spinn
 1. Depending on auditing needs, you can either commit the "runs" folder to your repo or only keep the "binder" folder committed.
    1. In case of strict auditing needs, we recommend you add auditing of commands in the local SDK as well as in your cloud provider
 
-## Installation
+# Installation
 
 We recommend using [uv](https://docs.astral.sh/uv/) for installing runbook as a cli tool. If you already use pipx, you can use that instead.
 
@@ -86,7 +86,7 @@ Or pin to a version
 uv tool install git+https://github.com/zph/runbook.git@$RUNBOOK_VERSION
 ```
 
-## CLI
+# CLI
 
 ```sh
 $RUNBOOK_HELP
@@ -136,7 +136,7 @@ For development we use the following tools:
 - [hermit](https://hermit.dev/) to manage developement tool dependencies (see .hermit/bin)
 - [uv](https://docs.astral.sh/uv/) python package manager and cli runner (see pyproject.toml)
 
-Necessary deps can be seen in [pyproject.toml](pyproject.toml) and .hermit/bin
+Necessary deps can be seen in pyproject.toml and .hermit/bin
 
 Use .hermit/bin/activate-hermit to activate the environment.
 

README.md

@@ -31,7 +31,7 @@ runbook run runbook-name.ipynb
 
 # Background
 
-### What is a Runbook?
+## What is a Runbook?
 A runbook is an executable document that combines:
 - Clear markdown documentation
 - Runnable code blocks
@@ -40,13 +40,13 @@ A runbook is an executable document that combines:
 
 It's ideal for operations like encoding your Disaster Recovery Operations, spinning up a new cluster, or restoring from snapshots.
 
-### When Should You Use This?
+## When Should You Use This?
 - ✅ When you need **semi-automated tools** with audit trails and safety checks
 - ✅ When you want **rapid iteration** on operational procedures with built-in rollback steps
 - ✅ When you need something more powerful than shell scripts but don't want to build a full application
 - ✅ When you want to make complex operations both **safe and repeatable**
 
-### Runbook Best Practices
+## Runbook Best Practices
 1. Structure your runbooks with:
    - Clear purpose and summary
    - Step-by-step descriptions
@@ -72,7 +72,7 @@ It's ideal for operations like encoding your Disaster Recovery Operations, spinn
 1. Depending on auditing needs, you can either commit the "runs" folder to your repo or only keep the "binder" folder committed.
    1. In case of strict auditing needs, we recommend you add auditing of commands in the local SDK as well as in your cloud provider
 
-## Installation
+# Installation
 
 We recommend using [uv](https://docs.astral.sh/uv/) for installing runbook as a cli tool. If you already use pipx, you can use that instead.
 
@@ -86,7 +86,7 @@ Or pin to a version
 uv tool install git+https://github.com/zph/runbook.git@1.0.0-rc2
 ```
 
-## CLI
+# CLI
 
 ```sh
 Usage: runbook [OPTIONS] COMMAND [ARGS]...
@@ -98,16 +98,16 @@ Options:
   --help      Show this message and exit.
 
 Commands:
-  check    Check language validity and formatting of a notebook.
-  convert  Convert an existing runbook to different format
-  create   Create a new runbook from [template]
-  diff     Diff two notebooks
+  check    Check the language validity and formatting of a runbook.
+  convert  Convert a runbook between different formats
+  create   Create a new runbook from a template
+  diff     Compare two runbooks and show their differences
   edit     Edit an existing runbook
   init     Initialize a folder as a runbook repository
-  list     list runbooks
+  list     List runbooks
   plan     Prepares the runbook for execution by injecting parameters.
   review   [Unimplemented] Entrypoint for reviewing runbook
-  run      Run a notebook
+  run      Run a runbook
   show     Show runbook parameters and metadata
   version  Display version information about runbook
 ```
@@ -156,7 +156,7 @@ For development we use the following tools:
 - [hermit](https://hermit.dev/) to manage developement tool dependencies (see .hermit/bin)
 - [uv](https://docs.astral.sh/uv/) python package manager and cli runner (see pyproject.toml)
 
-Necessary deps can be seen in [pyproject.toml](pyproject.toml) and .hermit/bin
+Necessary deps can be seen in pyproject.toml and .hermit/bin
 
 Use .hermit/bin/activate-hermit to activate the environment.
 

docs/README.md

@@ -31,7 +31,7 @@ runbook run runbook-name.ipynb
 
 # Background
 
-### What is a Runbook?
+## What is a Runbook?
 A runbook is an executable document that combines:
 - Clear markdown documentation
 - Runnable code blocks
@@ -40,13 +40,13 @@ A runbook is an executable document that combines:
 
 It's ideal for operations like encoding your Disaster Recovery Operations, spinning up a new cluster, or restoring from snapshots.
 
-### When Should You Use This?
+## When Should You Use This?
 - ✅ When you need **semi-automated tools** with audit trails and safety checks
 - ✅ When you want **rapid iteration** on operational procedures with built-in rollback steps
 - ✅ When you need something more powerful than shell scripts but don't want to build a full application
 - ✅ When you want to make complex operations both **safe and repeatable**
 
-### Runbook Best Practices
+## Runbook Best Practices
 1. Structure your runbooks with:
    - Clear purpose and summary
    - Step-by-step descriptions
@@ -72,7 +72,7 @@ It's ideal for operations like encoding your Disaster Recovery Operations, spinn
 1. Depending on auditing needs, you can either commit the "runs" folder to your repo or only keep the "binder" folder committed.
    1. In case of strict auditing needs, we recommend you add auditing of commands in the local SDK as well as in your cloud provider
 
-## Installation
+# Installation
 
 We recommend using [uv](https://docs.astral.sh/uv/) for installing runbook as a cli tool. If you already use pipx, you can use that instead.
 
@@ -86,7 +86,7 @@ Or pin to a version
 uv tool install git+https://github.com/zph/runbook.git@1.0.0-rc2
 ```
 
-## CLI
+# CLI
 
 ```sh
 Usage: runbook [OPTIONS] COMMAND [ARGS]...
@@ -98,16 +98,16 @@ Options:
   --help      Show this message and exit.
 
 Commands:
-  check    Check language validity and formatting of a notebook.
-  convert  Convert an existing runbook to different format
-  create   Create a new runbook from [template]
-  diff     Diff two notebooks
+  check    Check the language validity and formatting of a runbook.
+  convert  Convert a runbook between different formats
+  create   Create a new runbook from a template
+  diff     Compare two runbooks and show their differences
   edit     Edit an existing runbook
   init     Initialize a folder as a runbook repository
-  list     list runbooks
+  list     List runbooks
   plan     Prepares the runbook for execution by injecting parameters.
   review   [Unimplemented] Entrypoint for reviewing runbook
-  run      Run a notebook
+  run      Run a runbook
   show     Show runbook parameters and metadata
   version  Display version information about runbook
 ```
@@ -156,7 +156,7 @@ For development we use the following tools:
 - [hermit](https://hermit.dev/) to manage developement tool dependencies (see .hermit/bin)
 - [uv](https://docs.astral.sh/uv/) python package manager and cli runner (see pyproject.toml)
 
-Necessary deps can be seen in [pyproject.toml](pyproject.toml) and .hermit/bin
+Necessary deps can be seen in pyproject.toml and .hermit/bin
 
 Use .hermit/bin/activate-hermit to activate the environment.
 

docs/_static/.gitkeep

@@ -6,11 +6,6 @@
 Runbook CLI
 =====================
 
-Add your content using ``reStructuredText`` syntax. See the
-`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
-documentation for details.
-
-
 .. toctree::
    :maxdepth: 2
    :caption: Contents:

docs/_templates/.gitkeep

@@ -7,7 +7,6 @@
     create,
     diff,
     edit,
-    export,
     init,
     list,
     plan,
@@ -47,7 +46,6 @@ def cli(ctx, cwd):
 cli.add_command(version)
 cli.add_command(list)
 cli.add_command(show)
-# cli.add_command(export)
 cli.name = "runbook"
 cli
 

docs/cli.rst

@@ -25,7 +25,24 @@
 )
 @click.pass_context
 def check(ctx, filename, command):
-    """Check language validity and formatting of a notebook."""
+    """Check the language validity and formatting of a runbook.
+
+    This command validates the syntax and formatting of runbook cells based on the kernel
+    specified in the notebook's metadata. By default:
+    - For Python kernels: uses 'black' to check code formatting
+    - For Deno kernels: uses 'deno check' to validate TypeScript/JavaScript
+
+    FILENAME: Path to the runbook file to check.
+
+    Options:
+        --command, -c: Specify a custom validation command. Use {} as a placeholder for the
+                      filename (e.g., 'mycheck {} --strict'). This overrides the default
+                      checker for the kernel.
+
+    Exit codes:
+        0: Check passed successfully
+        Non-zero: Check failed, see error output for details
+    """
     full_path = path.abspath(filename)
     content = None
     with open(full_path, "r") as f:

runbook/cli/__init__.py

@@ -17,7 +17,27 @@
 )
 @click.pass_context
 def convert(ctx, filename, output):
-    """Convert an existing runbook to different format"""
+    """Convert a runbook between different formats
+
+    This command converts notebooks between various formats using jupytext.
+    Supported conversions include:
+    - .ipynb to .py (Python script)
+    - .ipynb to .ts (Deno notebook)
+    - .ipynb to .md (Markdown)
+    - And other formats supported by jupytext
+
+    FILENAME: Path to the source notebook file to convert.
+    OUTPUT: Destination path for the converted file. The format is determined
+           by the file extension.
+
+    Examples:
+        runbook convert notebook.ipynb script.py   # Convert to Python script
+        runbook convert notebook.ipynb notebook.ts   # Convert to Deno notebook
+        runbook convert notebook.ipynb notebook.md   # Convert to Markdown
+
+    The conversion preserves cell metadata, notebook metadata, and execution outputs
+    where applicable.
+    """
     # Must override argv because it's used in launch instance and there isn't a way
     # to pass via argument in ExtensionApp.lauch_instance
     # TODO:

runbook/cli/commands/check.py

@@ -14,6 +14,7 @@
     default="./runbooks/binder/_template-deno.ipynb",
     type=click.Path(exists=True, file_okay=True),
     callback=validate_template,
+    help="Path to the template file to use",
 )
 
 # TODO: switch to language and template defaulting to Deno
@@ -24,10 +25,34 @@
     envvar="LANGUAGE",
     default="deno",
     callback=validate_create_language,
+    help="Language to use for the runbook",
 )
 @click.pass_context
 def create(ctx, filename, template, language):
-    """Create a new runbook from [template]"""
+    """Create a new runbook from a template
+
+    This command creates a new runbook using a specified template
+    or language preset. The new runbook will be created in the runbooks/binder directory.
+
+    FILENAME: Name for the new runbook file (e.g., 'maintenance-task.ipynb').
+             Should be a basename only, without directory path.
+
+    Options:
+        --template, -t: Path to a custom template runbook to use as a base.
+                       Can be set via TEMPLATE environment variable.
+                       Default: ./runbooks/binder/_template-deno.ipynb
+
+        --language, -l: Shortcut to use a predefined language template.
+                       Can be set via LANGUAGE environment variable.
+                       Default: deno
+
+    Examples:
+        runbook create maintenance-task.ipynb              # Creates using default Deno template
+        runbook create task.ipynb -l python               # Creates using Python template
+        runbook create task.ipynb -t custom-template.ipynb # Creates from custom template
+
+    The command will create the notebook and display the edit command to open it.
+    """
 
     if language:
         template = language

runbook/cli/commands/convert.py

@@ -18,7 +18,23 @@
 )
 @click.pass_context
 def diff(ctx, notebook_1, notebook_2):
-    """Diff two notebooks"""
+    """Compare two runbooks and show their differences
+
+    This command uses nbdime to display a detailed comparison between two runbooks.
+
+    Arguments:
+        NOTEBOOK_1: Path to the first runbook for comparison
+        NOTEBOOK_2: Path to the second runbook for comparison
+
+    Examples:
+        runbook diff notebook1.ipynb notebook2.ipynb     # Compare two notebooks
+        runbook diff original.ipynb modified.ipynb       # Show changes between versions
+
+    The diff output will be displayed in a terminal-friendly format, with:
+    - Added content in green
+    - Removed content in red
+    - Modified content showing both versions
+    """
     argv = [path.abspath(notebook_1), path.abspath(notebook_2)]
     from nbdime import nbdiffapp
 

runbook/cli/commands/create.py

@@ -17,13 +17,15 @@
     envvar="DIRECTORY",
     default="runbooks",
     type=click.Path(exists=False, dir_okay=True),
+    help="Path to the runbook directory",
 )
 @click.option(
     "-s",
     "--skip-confirmation",
     envvar="SKIP_CONFIRMATION",
     default=False,
     type=click.BOOL,
+    help="Skip confirmation prompt",
 )
 @click.pass_context
 def init(ctx, directory, skip_confirmation):

runbook/cli/commands/diff.py

@@ -4,7 +4,7 @@
 @click.command()
 @click.pass_context
 def list(ctx):
-    """list runbooks"""
+    """List runbooks"""
     import glob
 
     from rich import print as rprint