Repository: axodotdev/cargo-dist
Pull request #254 (2023-05-12 21:36:30)

fix a few typos


Patch:
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 37349fc9..e9d29b57 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -24,29 +24,22 @@ jobs:
   fmt:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v1
-      - uses: actions-rs/toolchain@v1
+      - uses: actions/checkout@v3
+      - uses: dtolnay/rust-toolchain@master
         with:
           toolchain: stable
-          profile: minimal
           components: rustfmt
-          override: true
-      - uses: actions-rs/cargo@v1
-        with:
-          command: fmt
-          args: --all -- --check
+      - run: cargo fmt --all -- --check
 
   # Check that clippy is appeased
   clippy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v1
-      - uses: actions-rs/toolchain@v1
+      - uses: actions/checkout@v3
+      - uses: dtolnay/rust-toolchain@master
         with:
           toolchain: stable
-          profile: minimal
           components: clippy
-          override: true
       - uses: actions-rs/clippy-check@v1
         env:
           PWD: ${{ env.GITHUB_WORKSPACE }}
@@ -61,17 +54,12 @@ jobs:
      RUSTDOCFLAGS: -Dwarnings
    steps:
      - uses: actions/checkout@master
-     - uses: actions-rs/toolchain@v1
+     - uses: dtolnay/rust-toolchain@master
        with:
          toolchain: stable
-         profile: minimal
          components: rust-docs
-         override: true
      - uses: swatinem/rust-cache@v1
-     - uses: actions-rs/cargo@v1
-       with:
-         command: doc
-         args: --workspace --no-deps
+     - run: cargo doc --workspace --no-deps
 
   # Build and run tests/doctests/examples on all platforms
   # FIXME: look into `cargo-hack` which lets you more aggressively
@@ -86,37 +74,23 @@ jobs:
     steps:
       # Setup tools
       - uses: actions/checkout@master
-      - uses: actions-rs/toolchain@v1
+      - uses: dtolnay/rust-toolchain@master
         with:
           toolchain: ${{ matrix.rust }}
-          profile: minimal
-          override: true
       - uses: swatinem/rust-cache@v1
       # Run the tests/doctests (default features)
-      - uses: actions-rs/cargo@v1
+      - run: cargo test --workspace
         env:
           PWD: ${{ env.GITHUB_WORKSPACE }}
-        with:
-          command: test
-          args: --workspace
       # Run the tests/doctests (all features)
-      - uses: actions-rs/cargo@v1
+      - run: cargo test --workspace --all-features
         env:
           PWD: ${{ env.GITHUB_WORKSPACE }}
-        with:
-          command: test
-          args: --workspace --all-features
       # Test the examples (default features)
-      - uses: actions-rs/cargo@v1
+      - run: cargo test --workspace --examples --bins
         env:
           PWD: ${{ env.GITHUB_WORKSPACE }}
-        with:
-          command: test
-          args: --workspace --examples --bins
       # Test the examples (all features)
-      - uses: actions-rs/cargo@v1
+      - run: cargo test --workspace --all-features --examples --bins
         env:
           PWD: ${{ env.GITHUB_WORKSPACE }}
-        with:
-          command: test
-          args: --workspace --all-features --examples --bins
\ No newline at end of file
diff --git a/.github/workflows/web.yml b/.github/workflows/web.yml
index 96ef5866..d999d4cf 100644
--- a/.github/workflows/web.yml
+++ b/.github/workflows/web.yml
@@ -52,33 +52,23 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       # Setup
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
         with:
           fetch-depth: 0
-      - uses: actions-rs/toolchain@v1
-        with:
-          toolchain: stable
-          override: true
-
-      # OPTIONAL: build your mdbook
-      # Note that "./book/" is the directory in our repo where the book.toml is
-      # and we pass that to mdbook. You also need to tell oranda.json this with
-      #   "md_book": "./book/book/"
-      # ("book" being the dir where mdbook writes is output)
-      - 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: |
-          mdbook build book
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: swatinem/rust-cache@v2
       
-      # Install and run oranda
+      # Install mdbook plugins
+      - name: Install mdbook plugins
+        run: |
+          cargo install --locked mdbook-toc@0.11.2
+          cargo install --locked mdbook-linkcheck@0.7.7
+
+      # Install and run oranda (and mdbook)
       # This will write all output to ./public/ (including copying mdbook's output to there)
       - name: Install and run oranda
         run: |
-          curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/oranda/releases/download/v0.0.3/oranda-installer.sh | sh
+          curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/oranda/releases/download/v0.1.0-prerelease.1/oranda-installer.sh | sh
           cd cargo-dist
           oranda build
 
diff --git a/book/book.toml b/book/book.toml
index 9a781de7..93d2e2a7 100644
--- a/book/book.toml
+++ b/book/book.toml
@@ -8,3 +8,9 @@ title = "cargo-dist"
 [output.html]
 git-repository-url = "https://github.com/axodotdev/cargo-dist"
 edit-url-template = "https://github.com/axodotdev/cargo-dist/edit/main/book/{path}"
+
+# [output.linkcheck]
+# warning-policy = "error"
+
+[preprocessor.toc]
+command = "mdbook-toc"
diff --git a/book/src/artifacts.md b/book/src/artifacts.md
index d873e86b..bd450f96 100644
--- a/book/src/artifacts.md
+++ b/book/src/artifacts.md
@@ -1,5 +1,7 @@
 # Artifacts
 
+<!-- toc -->
+
 cargo-dist's primary role is to produce "Artifacts", either to use locally or to upload as part of a release announcement. Here's a listing of the supported kinds!
 
 
@@ -31,7 +33,7 @@ This feature is currently disabled [pending a rework][rework-symbols], but basic
 
 Most other kinds of artifact are referred to as "installers", because they generally exist as ways of downloading and installing the binaries that were made for the executable-zips.
 
-[See the full docs on installers for details][installers-docs].
+[See the full docs on installers for details][installers].
 
 
 
diff --git a/book/src/cargo-release-guide.md b/book/src/cargo-release-guide.md
index d03bd939..bf3fc083 100644
--- a/book/src/cargo-release-guide.md
+++ b/book/src/cargo-release-guide.md
@@ -1,5 +1,7 @@
 # Using cargo-release
 
+<!-- toc -->
+
 > NOTE: It will be helpful to read [the section on cargo-dist Announcement Tags][announcements], because that is the interface boundary between cargo-release and cargo-dist. TL;DR: cargo-dist interprets a git tag of "v1.0.0" as "Announce/Release the whole workspace" (Unified Announcement) and "my-app-v1.0.0" as "Announce/Release that one package" (Singular Announcement).
 
 > NOTE: this guide assumes you're running [cargo-release v0.22.0][release-22] or greater, as that version made several significant changes to default behaviours (for the better!).
diff --git a/book/src/cli.md b/book/src/cli.md
index 2415e422..7c93c526 100644
--- a/book/src/cli.md
+++ b/book/src/cli.md
@@ -1,1 +1,7 @@
-{{#include ../../cargo-dist/tests/snapshots/cli_tests__markdown-help.snap:6:}}
\ No newline at end of file
+# cargo-dist CLI Manual
+
+<!-- toc -->
+
+{{#include ../../cargo-dist/tests/snapshots/cli_tests__markdown-help.snap:7:}}
+
+[workspace.metadata.dist]: ./config.md#metadatadist
\ No newline at end of file
diff --git a/book/src/concepts.md b/book/src/concepts.md
index ec080173..7aee2ba1 100644
--- a/book/src/concepts.md
+++ b/book/src/concepts.md
@@ -1,5 +1,7 @@
 # Concepts
 
+<!-- toc -->
+
 Here's the section where I use a bunch of words Capitalized Words to indicate they are a Special Concept in cargo-dist as I try to explain how it works. These are the "advanced" docs of cargo-dist, for the "beginner" docs see [the guide][guide] for the "beginner" docs.
 
 An invocation of cargo-dist has 4 major inputs:
diff --git a/book/src/config.md b/book/src/config.md
index 44a233a0..dec62fb0 100644
--- a/book/src/config.md
+++ b/book/src/config.md
@@ -1,5 +1,7 @@
 # Config
 
+<!-- toc -->
+
 cargo-dist accepts configuration from the following sources, in order of increasing preference (that is, CLI flags generally replace things specified in your Cargo.toml):
 
 * Relevant [Cargo.toml fields][cargo-manifest] like "repository" and "readme"
@@ -116,7 +118,7 @@ By default all runs of `cargo-dist` will be trying to handle all platforms speci
 
 Example: `installers = ["shell", "powershell"]`
 
-This is a list of installers you want to be made for your application(s). In principle this can be overridden on a per-package basis but that is not well tested. See [the full docs on installers for the full list of values][].
+This is a list of installers you want to be made for your application(s). In principle this can be overridden on a per-package basis but that is not well tested. See [the full docs on installers for the full list of values][installers].
 
 See "repository" for some discussion on the "Artifact Download URL".
 
diff --git a/book/src/install.md b/book/src/install.md
index ef05fa33..b600fa0d 100644
--- a/book/src/install.md
+++ b/book/src/install.md
@@ -1,5 +1,7 @@
 # Install
 
+<!-- toc -->
+
 Surprise! The tool for prebuilt shippable binaries has way too many ways to install it!
 Whichever way you choose to install it, it should be invocable as `cargo dist ...`. If you insist on invoking the binary directly as `cargo-dist` you must still add the extra `dist` arg and invoke it as `cargo-dist dist ...` (a quirk of the way cargo invokes subcommands).
 
diff --git a/book/src/installers.md b/book/src/installers.md
index b3c9e208..20fd6000 100644
--- a/book/src/installers.md
+++ b/book/src/installers.md
@@ -1,5 +1,7 @@
 # Installers
 
+<!-- toc -->
+
 The core functionality of cargo-dist is to build your binaries and produce tarballs/zips containing them. Basically every other kind of file it produces is considered an "installer" that helps download/install those binaries.
 
 > Currently all supported installers are "global"/"universal" installers that detect the current platform and download and unpack the appropriate tarball/zip. This currently requires CI support to be enabled so we can ensure the files are hosted somewhere and now where to fetch them from.
@@ -221,8 +223,7 @@ Although that's still missing things like [Windows crt-static workarounds][crt-s
 
 
 [issue-info-install]: https://github.com/axodotdev/cargo-dist/issues/72
-[issue-npm-readme]: https://github.com/axodotdev/cargo-dist/issues/238
-[issue-npm-install]: https://github.com/axodotdev/cargo-dist/issues/245
+[issue-npm-ci]: https://github.com/axodotdev/cargo-dist/issues/245
 [linux-pm-issue]: https://github.com/axodotdev/cargo-dist/issues/76
 [windows-pm-issue]: https://github.com/axodotdev/cargo-dist/issues/87
 [msi-installer-issue]: https://github.com/axodotdev/cargo-dist/issues/23
diff --git a/book/src/reference.md b/book/src/reference.md
index 72fc38da..8e6505dc 100644
--- a/book/src/reference.md
+++ b/book/src/reference.md
@@ -1,3 +1,3 @@
 # Reference
 
-The following sections are more focused on precise details.
\ No newline at end of file
+The following sections are more focused on precise details.
diff --git a/book/src/simple-guide.md b/book/src/simple-guide.md
index 9dee579a..8e731d0e 100644
--- a/book/src/simple-guide.md
+++ b/book/src/simple-guide.md
@@ -1,5 +1,7 @@
 # Guide: A Simple Application
 
+<!-- toc -->
+
 Let's start with the kind of simple [Cargo Workspace][workspace] you would get from `cargo new my-app` (or `cargo init my-app`): a single package that defines a [binary target][bin]. This is exactly the situation the [Way-Too-Quickstart][way-too-quickstart] should work perfectly for. Here we're going to take it a bit slower.
 
 Our goal will be to setup a Github CI workflow that announces a new release of our application with a Github Release. The workflow will also build our application for the 3 major desktop platforms, wrap the binaries in zips/tarballs, and upload them to the Github Release. The Github Release's text will also include the relevant release notes from our RELEASES.md file.
@@ -18,7 +20,7 @@ You can rerun `init` as many times as you want, as it also functions as an "upda
 cargo dist init
 ```
 
-[`init`][] on its own just edits your Cargo.toml to include the recommended defaults. If you have enabled CI support, it will also run `cargo dist generate-ci` after setting things up. This ensures your config and your CI scripts are in sync, but will unfortunately clobber any hand-edits you made to the scripts.
+[`init`][init] on its own just edits your Cargo.toml to include the recommended defaults. If you have enabled CI support, it will also run `cargo dist generate-ci` after setting things up. This ensures your config and your CI scripts are in sync, but will unfortunately clobber any hand-edits you made to the scripts.
 
 Let's look at those defaults that were added (yes those comments are generated too, you will never stop me from adding more docs!!!):
 
diff --git a/book/src/way-too-quickstart.md b/book/src/way-too-quickstart.md
index ef236304..d4ce9d5f 100644
--- a/book/src/way-too-quickstart.md
+++ b/book/src/way-too-quickstart.md
@@ -1,15 +1,11 @@
 # Way-Too-Quickstart
 
+<!-- toc -->
+
 > TLDR: cargo-dist is a souped up version of `cargo build` which handles building tarballs/zips and [installers][]. It also knows how to generate Github CI for orchestrating itself and uploading its output to a new Github Release. You can use cargo-dist if you don't care about that CI stuff, but this guide assumes that you do.
 >
 > This quickstart is a bit *too* quick because there's some important nuances to "announcing and building releases" that depend on the way you like to structure and version your workspace. We will blatantly ignore those nuances and show you the Happiest Happy Path (a workspace with one crate that defines a binary). Checkout [the guide][guide] for more details on what you should *actually* do.
 
-The quickstart has three parts: 
-
-1. setting up cargo-dist
-2. testing locally
-3. cutting a release of your project on Github
-
 
 
 ## Setup
diff --git a/book/src/workspace-guide.md b/book/src/workspace-guide.md
index 88c3a096..352c8c9d 100644
--- a/book/src/workspace-guide.md
+++ b/book/src/workspace-guide.md
@@ -1,5 +1,7 @@
 # Guide: More Complex Workspaces
 
+<!-- toc -->
+
 Now that we've [looked at a simple example][simple-guide] with `cargo new`, let's start looking at ways to make a [Cargo Workspace][workspace] more complicated, and how cargo-dist will deal with them.
 
 But first, let's define some precise terminology: 
diff --git a/cargo-dist/oranda.json b/cargo-dist/oranda.json
index 7e88916a..3a68c0fb 100644
--- a/cargo-dist/oranda.json
+++ b/cargo-dist/oranda.json
@@ -8,7 +8,9 @@
     "image_alt": "axo",
     "twitter_account": "@axodotdev"
   },
-  "md_book": "../book/book",
+  "mdbook": {
+    "path": "../book"
+  },
   "artifacts": {
     "cargo_dist": true,
     "package_managers": {
diff --git a/cargo-dist/src/cli.rs b/cargo-dist/src/cli.rs
index 6c703118..686fcd1b 100644
--- a/cargo-dist/src/cli.rs
+++ b/cargo-dist/src/cli.rs
@@ -21,8 +21,7 @@ pub enum FakeCli {
 #[clap(args_conflicts_with_subcommands = true)]
 /// Shippable packaging for Rust.
 ///
-/// When run without a subcommand, `cargo dist` will invoke the `build`
-/// subcommand. See `cargo dist help build` for more details.
+/// See 'init', 'build' and 'plan' for the 3 most important subcommands.
 pub struct Cli {
     /// Subcommands ("no subcommand" defaults to `build`)
     #[clap(subcommand)]
@@ -146,7 +145,7 @@ pub enum Commands {
     /// (although it adds --output-format=json so that it's machine-readable).
     ///
     /// This is an alias for the lower-level 'manifest' command with the
-    /// appropriate flags forced for asking for "everything":
+    /// appropriate flags forced for asking for "everything"
     ///
     ///     cargo dist manifest --artifacts=all --no-local-paths
     ///
diff --git a/cargo-dist/src/init.rs b/cargo-dist/src/init.rs
index d5ff06b6..c38b770b 100644
--- a/cargo-dist/src/init.rs
+++ b/cargo-dist/src/init.rs
@@ -101,7 +101,7 @@ fn init_dist_profile(_cfg: &Config, workspace_toml: &mut toml_edit::Document) ->
         // that enormous applications like chromium can become unbuildable), but definitely
         // eeks out a bit more from your binaries.
         //
-        // In principle cargo-dist is targetting True Shippable Binaries and so it's
+        // In principle cargo-dist is targeting True Shippable Binaries and so it's
         // worth it to go nuts getting every last drop out of your binaries... but a lot
         // of people are going to build binaries that might never even be used, so really
         // we're just burning a bunch of CI time for nothing.
diff --git a/cargo-dist/src/lib.rs b/cargo-dist/src/lib.rs
index fd3ee769..b5af4873 100644
--- a/cargo-dist/src/lib.rs
+++ b/cargo-dist/src/lib.rs
@@ -51,7 +51,7 @@ pub fn do_dist(cfg: &Config) -> Result<DistManifest> {
     // bundling up an executable the moment it's built! Note however that you shouldn't
     // parallelize Cargo invocations because it has global state that can get clobbered.
     // Most problematically if you do two builds with different feature flags the final
-    // binaries will get copied to the same location and clobber eachother :(
+    // binaries will get copied to the same location and clobber each other :(
 
     // First set up our target dirs so things don't have to race to do it later
     if !dist.dist_dir.exists() {
diff --git a/cargo-dist/src/main.rs b/cargo-dist/src/main.rs
index 68bdd5f1..b496a321 100644
--- a/cargo-dist/src/main.rs
+++ b/cargo-dist/src/main.rs
@@ -297,9 +297,9 @@ fn print_help_markdown(out: &mut dyn Write) -> std::io::Result<()> {
         let mut in_normal_options = false;
         for line in lines {
             if let Some(usage) = line.strip_prefix("Usage: ") {
-                writeln!(out, "### Usage:")?;
+                writeln!(out, "### Usage")?;
                 writeln!(out)?;
-                writeln!(out, "```")?;
+                writeln!(out, "```text")?;
                 writeln!(out, "{usage}")?;
                 writeln!(out, "```")?;
                 continue;
diff --git a/cargo-dist/src/tasks.rs b/cargo-dist/src/tasks.rs
index 478637ce..40341d83 100644
--- a/cargo-dist/src/tasks.rs
+++ b/cargo-dist/src/tasks.rs
@@ -29,7 +29,7 @@
 //!    * global Artifacts: artifacts that have only one version across all platforms
 //!    * ReleaseVariants: a target-specific part of a Release (my-app-v1.0.0-x86_64-apple-darwin)
 //!      * local Artifacts: artifacts that are per-Variant
-//!      * Binaries: a binary that should be built for a specifc Variant
+//!      * Binaries: a binary that should be built for a specific Variant
 //!   * BuildSteps: steps we should take to build the artifacts
 //!
 //! Note that much of this hierarchy is rearranged/simplified in dist-manifest.json!
@@ -729,7 +729,7 @@ pub enum StaticAssetKind {
     License,
     /// A CHANGLEOG or RELEASES file
     Changelog,
-    /// Some other miscellanious file
+    /// Some other miscellaneous file
     Other,
 }
 
@@ -1768,7 +1768,7 @@ impl<'pkg_graph> DistGraphBuilder<'pkg_graph> {
                 return;
             };
 
-        info!("succesfully parsed changelog!");
+        info!("successfully parsed changelog!");
         self.inner.announcement_title = Some(title);
         self.inner.announcement_changelog = Some(notes);
     }
@@ -1885,7 +1885,7 @@ impl<'pkg_graph> DistGraphBuilder<'pkg_graph> {
             }
         }
 
-        info!("succesfully generated github release body!");
+        info!("successfully generated github release body!");
         // self.inner.artifact_download_url = Some(download_url);
         self.inner.announcement_github_body = Some(gh_body);
     }


Test patch:
diff --git a/cargo-dist/tests/snapshots/cli_tests__long-help.snap b/cargo-dist/tests/snapshots/cli_tests__long-help.snap
index 7ffd2844..4ee07336 100644
--- a/cargo-dist/tests/snapshots/cli_tests__long-help.snap
+++ b/cargo-dist/tests/snapshots/cli_tests__long-help.snap
@@ -5,7 +5,7 @@ expression: format_outputs(&output)
 stdout:
 Shippable packaging for Rust.
 
-When run without a subcommand, `cargo dist` will invoke the `build` subcommand. See `cargo dist help build` for more details.
+See 'init', 'build' and 'plan' for the 3 most important subcommands.
 
 Usage: cargo dist [OPTIONS]
        cargo dist <COMMAND>
diff --git a/cargo-dist/tests/snapshots/cli_tests__markdown-help.snap b/cargo-dist/tests/snapshots/cli_tests__markdown-help.snap
index 66edcefb..5910fd39 100644
--- a/cargo-dist/tests/snapshots/cli_tests__markdown-help.snap
+++ b/cargo-dist/tests/snapshots/cli_tests__markdown-help.snap
@@ -9,11 +9,11 @@ stdout:
 
 Shippable packaging for Rust.
 
-When run without a subcommand, `cargo dist` will invoke the `build` subcommand. See `cargo dist help build` for more details.
+See 'init', 'build' and 'plan' for the 3 most important subcommands.
 
-### Usage:
+### Usage
 
-```
+```text
 cargo dist [OPTIONS]
 ```
 cargo dist <COMMAND>
@@ -89,9 +89,9 @@ In the future we may try to make this look at the current git tags or something?
 ## cargo dist build
 Build artifacts
 
-### Usage:
+### Usage
 
-```
+```text
 cargo dist build [OPTIONS]
 ```
 
@@ -127,9 +127,9 @@ Setup or update cargo-dist
 
 This will interactively guide you through the process of selecting configuration options and will also automatically run 'cargo dist generate-ci' afterwards as necessary. It will also handle updating your project to a new version of cargo-dist if you're running one.
 
-### Usage:
+### Usage
 
-```
+```text
 cargo dist init [OPTIONS]
 ```
 
@@ -152,9 +152,9 @@ This subcommand accepts all the [global options](#global-options)
 ## cargo dist generate-ci
 Generate CI scripts for orchestrating cargo-dist
 
-### Usage:
+### Usage
 
-```
+```text
 cargo dist generate-ci [OPTIONS]
 ```
 
@@ -175,9 +175,9 @@ Notably it will default to only talking about artifacts for the host system, and
 
 'cargo dist plan' is an alias for this command that picks nicer defaults by forcing a couple flags to have specific values. You probably want that.
 
-### Usage:
+### Usage
 
-```
+```text
 cargo dist manifest [OPTIONS]
 ```
 
@@ -213,13 +213,13 @@ Get a plan of what to build (and check project status)
 
 If you want to know what running your cargo-dist CI will produce, this is the command for you! This is the exact command that CI will run to make its build plan and generate dist-manifest.json (although it adds --output-format=json so that it's machine-readable).
 
-### This is an alias for the lower-level 'manifest' command with the appropriate flags forced for asking for "everything"
+This is an alias for the lower-level 'manifest' command with the appropriate flags forced for asking for "everything"
 
 cargo dist manifest --artifacts=all --no-local-paths
 
-### Usage:
+### Usage
 
-```
+```text
 cargo dist plan [OPTIONS]
 ```
 
@@ -234,9 +234,9 @@ This subcommand accepts all the [global options](#global-options)
 ## cargo dist help
 Print this message or the help of the given subcommand(s)
 
-### Usage:
+### Usage
 
-```
+```text
 cargo dist help [COMMAND]
 ```