feat(docs): initial mdbook setup and hookup to oranda (#205)

.github/workflows/web.yml

@@ -19,6 +19,16 @@ jobs:
           toolchain: stable
           override: true
 
+      - name: Install mdbook
+        run: |
+          mkdir mdbook
+          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
+          echo `pwd`/mdbook >> $GITHUB_PATH
+      - name: Run mdbook build
+        run: |
+          cd book
+          mdbook build
+
       - name: Install oranda
         run: "curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/oranda/releases/download/v0.0.1/oranda-v0.0.1-installer.sh | sh"
 

Cargo.toml

@@ -142,3 +142,12 @@ debug = false
 # The profile that 'cargo dist' will build with
 [profile.dist]
 inherits = "release"
+
+[dev-dependencies]
+insta = { version = "1.28.0", features = ["yaml"] }
+
+[profile.dev.package.insta]
+opt-level = 3
+
+[profile.dev.package.similar]
+opt-level = 3

book/.gitignore

@@ -0,0 +1 @@
+book

book/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Kat Marchán"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Orogene"

book/src/SUMMARY.md

@@ -0,0 +1,17 @@
+# Summary
+
+[Introduction](./introduction.md)
+
+---
+
+# User Guide
+
+- [Configuration](./guide/configuration.md)
+
+---
+
+# Commands
+
+- [ping](./commands/ping.md)
+- [restore](./commands/restore.md)
+- [view](./commands/view.md)

book/src/commands/ping.md

@@ -0,0 +1 @@
+{{#include ../../../tests/snapshots/help__ping.snap:8:}}

book/src/commands/restore.md

@@ -0,0 +1 @@
+{{#include ../../../tests/snapshots/help__restore.snap:8:}}

book/src/commands/view.md

@@ -0,0 +1 @@
+{{#include ../../../tests/snapshots/help__view.snap:8:}}

book/src/guide/configuration.md

@@ -0,0 +1,6 @@
+# Configuration
+
+Orogene currently uses toml files for (persistent) configuration. Soon, this
+will be replaced with a [kdl](https://kdl.dev)-based configs.
+
+Until then, this page will stay mostly blank.

book/src/introduction.md

@@ -0,0 +1,5 @@
+# Introduction
+
+Orogene is a package manager for building up and writing `node_modules/`
+directories, as well as a general toolkit for working with related packages
+and APIs.

oranda.json

@@ -1,2 +1,4 @@
 {
+    "additional_pages": ["./CHANGELOG.md", "./CONTRIBUTING.md"],
+    "md_book": "./book/book"
 }

src/lib.rs

@@ -94,7 +94,7 @@
 use std::path::{Path, PathBuf};
 
 use async_trait::async_trait;
-use clap::{ArgMatches, CommandFactory, FromArgMatches as _, Parser, Subcommand};
+use clap::{ArgMatches, Args, CommandFactory, FromArgMatches as _, Parser, Subcommand};
 use directories::ProjectDirs;
 use miette::{IntoDiagnostic, Result};
 use oro_config::{OroConfig, OroConfigLayer, OroConfigOptions};
@@ -119,46 +119,46 @@ const MAX_RETAINED_LOGS: usize = 5;
 #[command(propagate_version = true)]
 pub struct Orogene {
     /// Package path to operate on.
-    #[arg(global = true, long)]
+    #[arg(help_heading = "Global Options", global = true, long)]
     root: Option<PathBuf>,
 
     /// Registry used for unscoped packages.
     ///
     /// Defaults to https://registry.npmjs.org.
-    #[arg(global = true, long)]
+    #[arg(help_heading = "Global Options", global = true, long)]
     registry: Option<Url>,
 
     /// Location of disk cache.
     ///
     /// Default location varies by platform.
-    #[arg(global = true, long)]
+    #[arg(help_heading = "Global Options", global = true, long)]
     cache: Option<PathBuf>,
 
     /// File to read configuration values from.
     ///
     /// When specified, global configuration loading is disabled and
     /// configuration values will only be read from this location.
-    #[arg(global = true, long)]
+    #[clap(help_heading = "Global Options", global = true, long)]
     config: Option<PathBuf>,
 
     /// Log output level/directive.
     ///
     /// Supports plain loglevels (off, error, warn, info, debug, trace) as
     /// well as more advanced directives in the format
     /// `target[span{field=value}]=level`.
-    #[clap(global = true, long)]
+    #[clap(help_heading = "Global Options", global = true, long)]
     loglevel: Option<String>,
 
     /// Disable all output.
-    #[arg(global = true, long, short)]
+    #[arg(help_heading = "Global Options", global = true, long, short)]
     quiet: bool,
 
     /// Format output as JSON.
-    #[arg(global = true, long)]
+    #[arg(help_heading = "Global Options", global = true, long)]
     json: bool,
 
     /// Disable progress bar display.
-    #[arg(global = true, long)]
+    #[arg(help_heading = "Global Options", global = true, long)]
     no_progress: bool,
 
     #[command(subcommand)]
@@ -351,6 +351,9 @@ pub enum OroCmd {
 
     /// Get information about a package.
     View(ViewCmd),
+
+    #[clap(hide = true)]
+    HelpMarkdown(HelpMarkdownCmd),
 }
 
 #[async_trait]
@@ -361,6 +364,7 @@ impl OroCommand for Orogene {
             OroCmd::Ping(cmd) => cmd.execute().await,
             OroCmd::Restore(cmd) => cmd.execute().await,
             OroCmd::View(cmd) => cmd.execute().await,
+            OroCmd::HelpMarkdown(cmd) => cmd.execute().await,
         }
     }
 }
@@ -377,6 +381,84 @@ impl OroConfigLayer for Orogene {
             OroCmd::View(ref mut cmd) => {
                 cmd.layer_config(args.subcommand_matches("view").unwrap(), conf)
             }
+            OroCmd::HelpMarkdown(ref mut cmd) => {
+                cmd.layer_config(args.subcommand_matches("help-markdown").unwrap(), conf)
+            }
+        }
+    }
+}
+
+#[derive(Debug, Args, OroConfigLayer)]
+pub struct HelpMarkdownCmd {
+    #[arg()]
+    command_name: String,
+}
+
+#[async_trait]
+impl OroCommand for HelpMarkdownCmd {
+    // Based on:
+    // https://github.com/axodotdev/cargo-dist/blob/b79a12e0942021ec304c5dcbf5e0cfcda3e6a4bb/cargo-dist/src/main.rs#L320
+    async fn execute(self) -> Result<()> {
+        let mut app = Orogene::command();
+
+        // HACK: This is a hack that forces clap to print global options for
+        // subcommands when calling `write_long_help` on them.
+        let mut _help_buf = Vec::new();
+        app.write_long_help(&mut _help_buf).into_diagnostic()?;
+
+        for subcmd in app.get_subcommands_mut() {
+            let name = subcmd.get_name();
+
+            if name != self.command_name {
+                continue;
+            }
+
+            println!("# oro {name}");
+            println!();
+
+            let mut help_buf = Vec::new();
+            subcmd.write_long_help(&mut help_buf).into_diagnostic()?;
+            let help = String::from_utf8(help_buf).into_diagnostic()?;
+
+            for line in help.lines() {
+                if let Some(usage) = line.strip_prefix("Usage: ") {
+                    println!("### Usage:");
+                    println!();
+                    println!("```");
+                    println!("oro {usage}");
+                    println!("```");
+                    continue;
+                }
+
+                if let Some(heading) = line.strip_suffix(':') {
+                    if !line.starts_with(' ') {
+                        println!("### {heading}");
+                        println!();
+                        continue;
+                    }
+                }
+
+                let line = line.trim();
+
+                if line.starts_with("- ") {
+                } else if line.starts_with('-') || line.starts_with('<') {
+                    println!("#### `{line}`");
+                    println!();
+                    continue;
+                }
+
+                if line.starts_with('[') {
+                    println!("\\{line}  ");
+                    continue;
+                }
+
+                println!("{line}");
+            }
+
+            println!();
+
+            return Ok(());
         }
+        Err(miette::miette!("Command not found: {self.command_name}"))
     }
 }

tests/help.rs

@@ -0,0 +1,37 @@
+use std::process::{Command, Output, Stdio};
+
+static BIN: &str = env!("CARGO_BIN_EXE_oro");
+
+#[test]
+fn ping_markdown() {
+    insta::assert_snapshot!("ping", sub_md("ping"));
+}
+
+#[test]
+fn restore_markdown() {
+    insta::assert_snapshot!("restore", sub_md("restore"));
+}
+
+#[test]
+fn view_markdown() {
+    insta::assert_snapshot!("view", sub_md("view"));
+}
+
+fn sub_md(subcmd: &str) -> String {
+    let output = Command::new(BIN)
+        .arg("help-markdown")
+        .arg(subcmd)
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .output()
+        .expect("Failed to execute process");
+
+    assert!(output.status.success(), "{}", format_output(&output));
+    format_output(&output)
+}
+
+fn format_output(output: &Output) -> String {
+    let stdout = std::str::from_utf8(&output.stdout).unwrap();
+    let stderr = std::str::from_utf8(&output.stderr).unwrap();
+    format!("stderr:\n{stderr}\nstdout:\n{stdout}")
+}

tests/snapshots/help__ping.snap

@@ -0,0 +1,70 @@
+---
+source: tests/help.rs
+expression: "sub_md(\"ping\")"
+---
+stderr:
+
+stdout:
+# oro ping
+
+Ping the registry
+
+### Usage:
+
+```
+oro ping [OPTIONS]
+```
+
+### Options
+
+#### `-h, --help`
+
+Print help (see a summary with '-h')
+
+#### `-V, --version`
+
+Print version
+
+### Global Options
+
+#### `--root <ROOT>`
+
+Package path to operate on
+
+#### `--registry <REGISTRY>`
+
+Registry used for unscoped packages.
+
+Defaults to https://registry.npmjs.org.
+
+#### `--cache <CACHE>`
+
+Location of disk cache.
+
+Default location varies by platform.
+
+#### `--config <CONFIG>`
+
+File to read configuration values from.
+
+When specified, global configuration loading is disabled and configuration values will only be read from this location.
+
+#### `--loglevel <LOGLEVEL>`
+
+Log output level/directive.
+
+Supports plain loglevels (off, error, warn, info, debug, trace) as well as more advanced directives in the format `target[span{field=value}]=level`.
+
+#### `-q, --quiet`
+
+Disable all output
+
+#### `--json`
+
+Format output as JSON
+
+#### `--no-progress`
+
+Disable progress bar display
+
+