Readme improvements

- Mention various chat channels - Add `intermodal-bin` package to package table - Document `bin/gen` - Add contributing section - Link to book type: documentation
2020-04-17 22:49:56 -07:00 · 2020-04-17 22:49:56 -07:00 · 9098d36840
commit 9098d36840
parent 04338e3501
12 changed files with 244 additions and 21 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -4,7 +4,8 @@ Changelog

 UNRELEASED - 2020-04-18
 -----------------------
- :art: [`xxxxxxxxxxxx`](https://github.com/casey/intermodal/commits/master) Merge documentation and changelog generation - _Casey Rodarmor <casey@rodarmor.com>_
+- :books: [`xxxxxxxxxxxx`](https://github.com/casey/intermodal/commits/master) Readme improvements - _Casey Rodarmor <casey@rodarmor.com>_
+- :art: [`04338e3501af`](https://github.com/casey/intermodal/commit/04338e3501afd155af47d0c4bda2c680d2a7a519) Merge documentation and changelog generation - _Casey Rodarmor <casey@rodarmor.com>_
 - :books: [`1f8023d13a39`](https://github.com/casey/intermodal/commit/1f8023d13a399e381176c20bbb6a71763b7c352a) Fix directory link in README - _Matt Boulanger <Celeo@users.noreply.github.com>_
 - :sparkles: [`cb8b5a691945`](https://github.com/casey/intermodal/commit/cb8b5a691945b8108676f95d2888774263be8cc8) Partially implement BEP 53 - Fixes [#245](https://github.com/casey/intermodal/issues/245) - _strickinato <aaronstrick@gmail.com>_
 - :books: [`6185d6c8a27c`](https://github.com/casey/intermodal/commit/6185d6c8a27c0d603f0434e98000c8e4a868dcc8) Add table of packages to readme ([#372](https://github.com/casey/intermodal/pull/372)) - Fixes [#369](https://github.com/casey/intermodal/issues/369) - _Casey Rodarmor <casey@rodarmor.com>_
--- a/README.md
+++ b/README.md
@ -5,11 +5,15 @@
 [![Book](https://img.shields.io/static/v1?logo=read-the-docs&label=book&message=imdl.io&color=informational)](https://imdl.io/book/)
 [![Chat](https://img.shields.io/discord/679283456261226516.svg?logo=discord&color=7289da)](https://discord.gg/HaaT5Qz)

-Intermodal is a user-friendly and featureful command-line BitTorrent metainfo utility. The binary is called `imdl` and runs on Linux, Windows, and macOS.
+Intermodal is a user-friendly and featureful command-line BitTorrent metainfo
+utility. The binary is called `imdl` and runs on Linux, Windows, and macOS.

-At the moment, creation, viewing, and verification of `.torrent` files is supported.
+At the moment, creation, viewing, and verification of `.torrent` files is
+supported. See [the book](https://imdl.io/book/) for examples and usage
+information.

-For more about the project and its goals, check out [this post](https://rodarmor.com/blog/intermodal).
+For more about the project and its goals, check out
+[this post](https://rodarmor.com/blog/intermodal).

 ![demonstration animation](https://raw.githubusercontent.com/casey/intermodal/master/www/demo.gif)

@ -21,6 +25,8 @@ For more about the project and its goals, check out [this post](https://rodarmor
  - [Pre-built binaries](#pre-built-binaries)
  - [Cargo](#cargo)
 - [Shell Completion Scripts](#shell-completion-scripts)
+- [Chat](#chat)
+- [Contributing](#contributing)
 - [Semantic Versioning](#semantic-versioning)
 - [Unstable Features](#unstable-features)
 - [Source Signatures](#source-signatures)
@ -35,10 +41,11 @@ If it does not, please open an issue!

 ### Packages

-| Operating System                                                     | Package Manager                     | Package                                                                   | Command              |
-|:--------------------------------------------------------------------:|:-----------------------------------:|:-------------------------------------------------------------------------:|---------------------:|
-| [Various](https://forge.rust-lang.org/release/platform-support.html) | [Cargo](https://www.rust-lang.org)  | [imdl](https://crates.io/crates/imdl)                                     | `cargo install imdl` |
-| [Arch Linux](https://www.archlinux.org)                              | [Yay](https://github.com/Jguer/yay) | [intermodal](https://aur.archlinux.org/packages/intermodal)<sup>AUR</sup> | `yay -S intermodal`  |
+| Operating System                                                     | Package Manager                     | Package                                                                           | Command                 |
+|:--------------------------------------------------------------------:|:-----------------------------------:|:---------------------------------------------------------------------------------:|:-----------------------:|
+| [Various](https://forge.rust-lang.org/release/platform-support.html) | [Cargo](https://www.rust-lang.org)  | [imdl](https://crates.io/crates/imdl)                                             | `cargo install imdl`    |
+| [Arch Linux](https://www.archlinux.org)                              | [Yay](https://github.com/Jguer/yay) | [intermodal-bin](https://aur.archlinux.org/packages/intermodal-bin)<sup>AUR</sup> | `yay -S intermodal-bin` |
+| [Arch Linux](https://www.archlinux.org)                              | [Yay](https://github.com/Jguer/yay) | [intermodal](https://aur.archlinux.org/packages/intermodal)<sup>AUR</sup>         | `yay -S intermodal`     |

 ### Pre-built binaries

@ -115,6 +122,59 @@ command will write the Z shell completion script to `$fpath[0]/_imdl`:
 $ imdl completions --shell zsh --dir $fpath[0]
 ```

+## Chat
+
+The primary chat is on [Discord](https://discord.gg/HaaT5Qz), but I try to also
+check [Keybase](https://keybase.io/team/intermodal) and
+[IRC](ircs://chat.freenode.net:6697/#intermodal) as time permits.
+
+## Contributing
+
+Your bug reports, feature requests, pull requests, and design help are much
+appreciated!
+
+Check out issues with the
+["good first issue" label](https://github.com/casey/intermodal/labels/good%20first%20issue)
+for some ideas.
+
+Quite a few files are generated by the program in `bin/gen`. Some files are
+generated from templates, so those templates should be edited to make changes
+to those files:
+
+- `bin/gen/templates/SUMMARY.md` -> `book/src/SUMMARY.md`
+- `bin/gen/templates/README.md` -> `README.md`
+- `bin/gen/templates/introduction.md` -> `book/src/introduction.md`
+
+Some files are completely generated, and so shouldn't be manually edited at
+all:
+
+- `CHANGELOG.md`
+- `book/src/commands/*`
+- `completions/*`
+- `man/*`
+
+All files can be regenerated by running `cargo run --package gen all`, or
+`just gen`, if you have [just](https://github.com/casey/just) installed.
+
+The changelog is generated from YAML metadata in commit messages. Here is an
+example commit message, with metadata:
+
+```
+Upgrade foo
+
+Upgrade foo to v7.5, which is much better.
+
+type: changed
+pr:
+- https://github.com/casey/intermodal/pull/1
+fixes:
+- https://github.com/intermodal/issues/2
+- https://github.com/intermodal/issues/3
+```
+
+The only required field is `type`. To see the possible values for `type`, run
+`cargo run --package gen commit-types`.
+
 ## Semantic Versioning

 Intermodal follows [semantic versioning](https://semver.org/).
--- a/bin/gen/config.yaml
+++ b/bin/gen/config.yaml
@ -39,3 +39,19 @@ examples:
  unstable: true
  text:     "Print information about a collection of torrents:"
  code:     "imdl --unstable torrent stats --input dir"
+
+packages:
+- operating-system: '[Various](https://forge.rust-lang.org/release/platform-support.html)'
+  package-manager:  '[Cargo](https://www.rust-lang.org)'
+  package:          '[imdl](https://crates.io/crates/imdl)'
+  command:          '`cargo install imdl`'
+
+- operating-system: '[Arch Linux](https://www.archlinux.org)'
+  package-manager:  '[Yay](https://github.com/Jguer/yay)'
+  package:          '[intermodal-bin](https://aur.archlinux.org/packages/intermodal-bin)<sup>AUR</sup>'
+  command:          '`yay -S intermodal-bin`'
+
+- operating-system: '[Arch Linux](https://www.archlinux.org)'
+  package-manager:  '[Yay](https://github.com/Jguer/yay)'
+  package:          '[intermodal](https://aur.archlinux.org/packages/intermodal)<sup>AUR</sup>'
+  command:          '`yay -S intermodal`'
--- a/bin/gen/src/common.rs
+++ b/bin/gen/src/common.rs
@ -22,9 +22,13 @@ pub(crate) use strum::VariantNames;
 pub(crate) use strum_macros::{EnumVariantNames, IntoStaticStr};
 pub(crate) use url::Url;

+// traits
+pub(crate) use crate::{command_ext::CommandExt, exit_status_ext::ExitStatusExt, row::Row};
+
+// structs and enums
 pub(crate) use crate::{
-  bin::Bin, changelog::Changelog, command_ext::CommandExt, config::Config, entry::Entry,
-  example::Example, exit_status_ext::ExitStatusExt, introduction::Introduction, kind::Kind,
-  metadata::Metadata, opt::Opt, project::Project, readme::Readme, release::Release,
-  subcommand::Subcommand, summary::Summary,
+  bin::Bin, changelog::Changelog, config::Config, entry::Entry, example::Example,
+  introduction::Introduction, kind::Kind, metadata::Metadata, opt::Opt, package::Package,
+  project::Project, readme::Readme, release::Release, subcommand::Subcommand, summary::Summary,
+  table::Table,
 };
--- a/bin/gen/src/config.rs
+++ b/bin/gen/src/config.rs
@ -6,6 +6,7 @@ const PATH: &str = "bin/gen/config.yaml";
 pub(crate) struct Config {
  pub(crate) changelog: BTreeMap<String, Metadata>,
  pub(crate) examples: Vec<Example>,
+  pub(crate) packages: Vec<Package>,
 }

 impl Config {
--- a/bin/gen/src/main.rs
+++ b/bin/gen/src/main.rs
@ -15,11 +15,14 @@ mod introduction;
 mod kind;
 mod metadata;
 mod opt;
+mod package;
 mod project;
 mod readme;
 mod release;
+mod row;
 mod subcommand;
 mod summary;
+mod table;

 #[throws]
 fn main() {
--- a/bin/gen/src/opt.rs
+++ b/bin/gen/src/opt.rs
@ -95,7 +95,7 @@ impl Opt {
    eprintln!("Generating readme…");
    let template = project.root.join("bin/gen/templates/README.md");

-    let readme = Readme::load(&template)?;
+    let readme = Readme::load(&project.config, &template)?;

    let mut text = readme.render()?;
    text.push('\n');
--- a/bin/gen/src/package.rs
+++ b/bin/gen/src/package.rs
@ -0,0 +1,25 @@
+use crate::common::*;
+
+#[derive(Deserialize, Clone)]
+#[serde(rename_all = "kebab-case")]
+pub(crate) struct Package {
+  operating_system: String,
+  package_manager: String,
+  package: String,
+  command: String,
+}
+
+impl Row for Package {
+  fn header() -> &'static [&'static str] {
+    &["Operating System", "Package Manager", "Package", "Command"]
+  }
+
+  fn entries(&self) -> Vec<&str> {
+    vec![
+      &self.operating_system,
+      &self.package_manager,
+      &self.package,
+      &self.command,
+    ]
+  }
+}
--- a/bin/gen/src/readme.rs
+++ b/bin/gen/src/readme.rs
@ -4,13 +4,14 @@ use crate::common::*;
 #[template(path = "README.md")]
 pub(crate) struct Readme {
  pub(crate) table_of_contents: String,
+  pub(crate) packages: Table<Package>,
 }

 const HEADING_PATTERN: &str = "(?m)^(?P<MARKER>#+) (?P<TEXT>.*)$";

 impl Readme {
  #[throws]
-  pub(crate) fn load(template: &Path) -> Readme {
+  pub(crate) fn load(config: &Config, template: &Path) -> Readme {
    let text = fs::read_to_string(template)?;

    let header_re = Regex::new(HEADING_PATTERN)?;
@ -32,6 +33,7 @@ impl Readme {

    Readme {
      table_of_contents: lines.join("\n"),
+      packages: Table::new(config.packages.clone()),
    }
  }
 }
--- a/bin/gen/src/row.rs
+++ b/bin/gen/src/row.rs
@ -0,0 +1,5 @@
+pub(crate) trait Row {
+  fn header() -> &'static [&'static str];
+
+  fn entries(&self) -> Vec<&str>;
+}
--- a/bin/gen/src/table.rs
+++ b/bin/gen/src/table.rs
@ -0,0 +1,52 @@
+use crate::common::*;
+
+pub(crate) struct Table<R> {
+  rows: Vec<R>,
+}
+
+impl<R: Row> Table<R> {
+  pub(crate) fn new(rows: Vec<R>) -> Table<R> {
+    Table { rows }
+  }
+}
+
+impl<R: Row> Display for Table<R> {
+  fn fmt(&self, f: &mut Formatter) -> fmt::Result {
+    let mut rows = Vec::new();
+    rows.push(R::header().to_vec());
+
+    for row in &self.rows {
+      rows.push(row.entries());
+    }
+
+    let mut widths = Vec::new();
+    widths.resize(rows[0].len(), 0);
+
+    for row in &rows {
+      for (width, entry) in widths.iter_mut().zip(row) {
+        *width = entry.len().max(*width);
+      }
+    }
+
+    for (i, row) in rows.iter().enumerate() {
+      if i == 1 {
+        for width in &widths {
+          write!(f, "|:{:-<width$}:", "", width = width)?;
+        }
+        writeln!(f, "|")?;
+      }
+
+      for (width, entry) in widths.iter().zip(row) {
+        write!(f, "| {:<width$} ", entry, width = width)?;
+      }
+
+      write!(f, "|")?;
+
+      if i < rows.len() - 1 {
+        writeln!(f)?;
+      }
+    }
+
+    Ok(())
+  }
+}
--- a/bin/gen/templates/README.md
+++ b/bin/gen/templates/README.md
@ -5,11 +5,15 @@
 [![Book](https://img.shields.io/static/v1?logo=read-the-docs&label=book&message=imdl.io&color=informational)](https://imdl.io/book/)
 [![Chat](https://img.shields.io/discord/679283456261226516.svg?logo=discord&color=7289da)](https://discord.gg/HaaT5Qz)

-Intermodal is a user-friendly and featureful command-line BitTorrent metainfo utility. The binary is called `imdl` and runs on Linux, Windows, and macOS.
+Intermodal is a user-friendly and featureful command-line BitTorrent metainfo
+utility. The binary is called `imdl` and runs on Linux, Windows, and macOS.

-At the moment, creation, viewing, and verification of `.torrent` files is supported.
+At the moment, creation, viewing, and verification of `.torrent` files is
+supported. See [the book](https://imdl.io/book/) for examples and usage
+information.

-For more about the project and its goals, check out [this post](https://rodarmor.com/blog/intermodal).
+For more about the project and its goals, check out
+[this post](https://rodarmor.com/blog/intermodal).

 ![demonstration animation](https://raw.githubusercontent.com/casey/intermodal/master/www/demo.gif)

@ -26,10 +30,7 @@ If it does not, please open an issue!

 ### Packages

-| Operating System                                                     | Package Manager                     | Package                                                                   | Command              |
-|:--------------------------------------------------------------------:|:-----------------------------------:|:-------------------------------------------------------------------------:|---------------------:|
-| [Various](https://forge.rust-lang.org/release/platform-support.html) | [Cargo](https://www.rust-lang.org)  | [imdl](https://crates.io/crates/imdl)                                     | `cargo install imdl` |
-| [Arch Linux](https://www.archlinux.org)                              | [Yay](https://github.com/Jguer/yay) | [intermodal](https://aur.archlinux.org/packages/intermodal)<sup>AUR</sup> | `yay -S intermodal`  |
+{{packages}}

 ### Pre-built binaries

@ -106,6 +107,59 @@ command will write the Z shell completion script to `$fpath[0]/_imdl`:
 $ imdl completions --shell zsh --dir $fpath[0]
 ```

+## Chat
+
+The primary chat is on [Discord](https://discord.gg/HaaT5Qz), but I try to also
+check [Keybase](https://keybase.io/team/intermodal) and
+[IRC](ircs://chat.freenode.net:6697/#intermodal) as time permits.
+
+## Contributing
+
+Your bug reports, feature requests, pull requests, and design help are much
+appreciated!
+
+Check out issues with the
+["good first issue" label](https://github.com/casey/intermodal/labels/good%20first%20issue)
+for some ideas.
+
+Quite a few files are generated by the program in `bin/gen`. Some files are
+generated from templates, so those templates should be edited to make changes
+to those files:
+
+- `bin/gen/templates/SUMMARY.md` -> `book/src/SUMMARY.md`
+- `bin/gen/templates/README.md` -> `README.md`
+- `bin/gen/templates/introduction.md` -> `book/src/introduction.md`
+
+Some files are completely generated, and so shouldn't be manually edited at
+all:
+
+- `CHANGELOG.md`
+- `book/src/commands/*`
+- `completions/*`
+- `man/*`
+
+All files can be regenerated by running `cargo run --package gen all`, or
+`just gen`, if you have [just](https://github.com/casey/just) installed.
+
+The changelog is generated from YAML metadata in commit messages. Here is an
+example commit message, with metadata:
+
+```
+Upgrade foo
+
+Upgrade foo to v7.5, which is much better.
+
+type: changed
+pr:
+- https://github.com/casey/intermodal/pull/1
+fixes:
+- https://github.com/intermodal/issues/2
+- https://github.com/intermodal/issues/3
+```
+
+The only required field is `type`. To see the possible values for `type`, run
+`cargo run --package gen commit-types`.
+
 ## Semantic Versioning

 Intermodal follows [semantic versioning](https://semver.org/).