Add table of contents to readme

type: documentation

.github/workflows/rust.yaml

@@ -26,13 +26,18 @@ jobs:
         cargo --version
         cargo clippy --version
     - name: Build
-      run: cargo build --verbose
+      run: cargo build --all --verbose
     - name: Test
-      run: cargo test --verbose
+      run: cargo test --all --verbose
     - name: Clippy
-      run: cargo clippy
+      run: cargo clippy --all
     - name: Format
-      run: cargo fmt -- --check
+      run: cargo fmt --all -- --check
     - name: Lint
       if: matrix.os != 'windows-latest'
       run: "! grep --color -REn 'FIXME|TODO|XXX' src"
+    - name: Readme
+      if: matrix.os != 'windows-latest'
+      run: |
+        cargo run --package update-readme toc
+        git diff --no-ext-diff --quiet --exit-code

Cargo.toml

@@ -33,13 +33,8 @@ walkdir           = "2"
 version = "1"
 features = ["derive"]
 
-[dev-dependencies]
-glob   = "0.3.0"
-regex  = "1.3.3"
-
-# generates the table of supported BEPs in README.md
-# not an example, but included as an example and not
-# a binary because examples can use dev dependencies
-[[example]]
-name = "generate-bep-table"
-path = "bin/generate-bep-table.rs"
+[workspace]
+members = [
+  # generate table of contents and table of supported BEPs in README.md
+  "bin/update-readme"
+]

README.md

@@ -1,5 +1,53 @@
 # intermodal: a 40' shipping container for the Internet
 
+## Manual
+
+- [General](#general)
+  - [Semantic Versioning](#semantic-versioning)
+  - [Unstable Features](#unstable-features)
+  - [Colored Output](#colored-output)
+- [Bittorrent](#bittorrent)
+  - [BEP Support](#bep-support)
+
+## General
+
+### Semantic Versioning
+
+Intermodal follows [semantic versioning](https://semver.org/).
+
+In particular:
+
+- v0.0.X: Breaking changes may be introduced at any time.
+- v0.X.Y: Breaking changes may only be introduced with a minor version number
+  bump.
+- vX.Y.Z: Breaking changes may only be introduced with a major version number
+  bump
+
+### Unstable Features
+
+To avoid premature stabilization and excessive version churn, unstable features
+are unavailable unless the `--unstable` / `-u` flag is passed. Unstable
+features may be changed or removed at any time.
+
+```
+$ imdl torrent stats --input tmp
+error: Feature `torrent stats subcommand` cannot be used without passing the `--unstable` flag
+$ imdl --unstable torrent stats tmp
+Torrents processed: 0
+Read failed:        0
+Decode failed:      0
+```
+
+### Colored Output
+
+Intermodal features colored help, error, and informational output. Colored
+output is disabled if Intermodal detects that it is not printing to a TTY.
+
+To disable colored output, set the `NO_COLOR` environment variable to any
+value or pass `--use-color never` on the command line.
+
+To force colored output, pass `--use-color always` on the command line.
+
 ## Bittorrent
 
 ### BEP Support
@@ -67,40 +115,3 @@
 | [53](http://bittorrent.org/beps/bep_0053.html) | :x:                | Magnet URI extension - Select specific file indices for download |
 | [54](http://bittorrent.org/beps/bep_0054.html) | :heavy_minus_sign: | The lt_donthave extension                                        |
 | [55](http://bittorrent.org/beps/bep_0055.html) | :heavy_minus_sign: | Holepunch extension                                              |
-
-## General Functionality
-
-### Colored Output
-
-Intermodal features colored help, error, and informational output. Colored
-output is disabled if Intermodal detects that it is not printing to a TTY.
-
-To disable colored output, set the `NO_COLOR` environment variable to any
-valu or pass `--use-color never` on the command line.
-
-To force colored output, pass `--use-color always` on the command line.
-
-## Semantic Versioning and Unstable Features
-
-Intermodal follows [semantic versioning](https://semver.org/).
-
-In particular:
-
-- v0.0.X: Breaking changes may be introduced at any time.
-- v0.X.Y: Breaking changes may only be introduced with a minor version number
-  bump.
-- vX.Y.Z: Breaking changes may only be introduced with a major version number
-  bump
-
-To avoid premature stabilization and excessive version churn, unstable features
-are unavailable unless the `--unstable` / `-u` flag is passed. Unstable
-features may be changed or removed at any time.
-
-```
-$ imdl torrent stats --input tmp
-error: Feature `torrent stats subcommand` cannot be used without passing the `--unstable` flag
-$ imdl --unstable torrent stats tmp
-Torrents processed: 0
-Read failed:        0
-Decode failed:      0
-```

bin/update-readme/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name    = "update-readme"
+version = "0.0.0"
+authors = ["Casey Rodarmor <casey@rodarmor.com>"]
+edition = "2018"
+publish = false
+
+[dependencies]
+glob      = "0.3.0"
+regex     = "1.3.3"
+structopt = "0.3"

bin/update-readme/src/bep.rs

@@ -0,0 +1,7 @@
+use crate::common::*;
+
+pub(crate) struct Bep {
+  pub(crate) number: usize,
+  pub(crate) title: String,
+  pub(crate) status: Status,
+}

bin/update-readme/src/common.rs

@@ -0,0 +1,15 @@
+// stdlib
+pub(crate) use std::{
+  error::Error,
+  fmt::{self, Display, Formatter},
+  fs,
+  str::FromStr,
+};
+
+// crates.io
+pub(crate) use glob::glob;
+pub(crate) use regex::Regex;
+pub(crate) use structopt::StructOpt;
+
+// local
+pub(crate) use crate::{bep::Bep, opt::Opt, status::Status};

bin/update-readme/src/main.rs

@@ -0,0 +1,10 @@
+mod bep;
+mod common;
+mod opt;
+mod status;
+
+use crate::common::*;
+
+fn main() -> Result<(), Box<dyn Error>> {
+  Opt::from_args().run()
+}