"humility spi" should take an optional device + "humility doc" (#110)

This adds a device parameter to the "humility spi" command, allowing
for a CS other than that associated with device 0 to be used.  By
default, the device is 0.

Broadly unrelated, this also adds a "humility doc" command that
provides more in-depth documentation for a specified command.  This
documentation is provided in situ in the command itself in the form of
rustdoc, which is both used to create the input for the "humility doc"
command and to create the documentation in README.md.  This also fixes
#15.

Note that "humility doc" requires the installation of "cargo-readme",
which in turn hit an annoying GH CI issue.  Thank you @sunshowers
for pointing us in the right direction!

  https://twitter.com/sunshowers6/status/1504174123005603841

Co-authored-by: Steve Klabnik <[email protected]>

Author: bcantrill

.github/buildomat/jobs/build-and-test.sh

@@ -34,6 +34,7 @@ fi
 pkg list -v "${need[@]}"
 
 cargo --version
+cargo install cargo-readme
 rustc --version
 
 banner test

.github/workflows/ci.yaml

@@ -22,6 +22,10 @@ jobs:
           toolchain: ${{ env.MSRV }}
           override: true
       - uses: Swatinem/rust-cache@v1
+      - name: Install cargo-readme
+        uses: baptiste0928/cargo-install@v1
+        with:
+          crate: cargo-readme
       - uses: actions-rs/cargo@v1
         with:
           command: check
@@ -41,6 +45,10 @@ jobs:
           toolchain: stable
           override: true
       - uses: Swatinem/rust-cache@v1
+      - name: Install cargo-readme
+        uses: baptiste0928/cargo-install@v1
+        with:
+          crate: cargo-readme
       - uses: actions-rs/cargo@v1
         with:
           command: check
@@ -61,6 +69,10 @@ jobs:
           toolchain: ${{ env.MSRV }}
           override: true
       - uses: Swatinem/rust-cache@v1
+      - name: Install cargo-readme
+        uses: baptiste0928/cargo-install@v1
+        with:
+          crate: cargo-readme
       - uses: actions-rs/cargo@v1
         with:
           command: test
@@ -82,6 +94,10 @@ jobs:
           override: true
           components: clippy
       - uses: Swatinem/rust-cache@v1
+      - name: Install cargo-readme
+        uses: baptiste0928/cargo-install@v1
+        with:
+          crate: cargo-readme
       - uses: actions-rs/cargo@v1
         with:
           command: clippy

.github/workflows/nightly.yml

@@ -20,6 +20,10 @@ jobs:
           toolchain: stable
           override: true
       - uses: Swatinem/rust-cache@v1
+      - name: Install cargo-readme
+        uses: baptiste0928/cargo-install@v1
+        with:
+          crate: cargo-readme
       - uses: actions-rs/cargo@v1
         with:
           command: build

Cargo.lock

@@ -13,6 +13,7 @@ members = [
     "cmd/apptable",
     "cmd/dashboard",
     "cmd/diagnose",
+    "cmd/doc",
     "cmd/dump",
     "cmd/etm",
     "cmd/gpio",
@@ -52,6 +53,10 @@ debug = true
 inherits = "dev"
 debug = false # default true
 
+[build-dependencies]
+cargo_metadata = "0.12.0"
+anyhow = "1.0.32"
+
 [dependencies]
 pmbus = { git = "https://github.com/oxidecomputer/pmbus" }
 hif = { git = "https://github.com/oxidecomputer/hif" }
@@ -62,6 +67,7 @@ humility-cmd = { path = "./humility-cmd" }
 cmd-apptable = { path = "./cmd/apptable", package = "humility-cmd-apptable" }
 cmd-dashboard = { path = "./cmd/dashboard", package = "humility-cmd-dashboard" }
 cmd-diagnose = { path = "./cmd/diagnose", package = "humility-cmd-diagnose" }
+cmd-doc = { path = "./cmd/doc", package = "humility-cmd-doc" }
 cmd-dump = { path = "./cmd/dump", package = "humility-cmd-dump" }
 cmd-etm = { path = "./cmd/etm", package = "humility-cmd-etm" }
 cmd-flash = { path = "./cmd/flash", package = "humility-cmd-flash" }