diff --git a/CHANGELOG.md b/CHANGELOG.md index bee2b42..8e53d9f 100644 --- 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 _ +- :books: [`xxxxxxxxxxxx`](https://github.com/casey/intermodal/commits/master) Readme improvements - _Casey Rodarmor _ +- :art: [`04338e3501af`](https://github.com/casey/intermodal/commit/04338e3501afd155af47d0c4bda2c680d2a7a519) Merge documentation and changelog generation - _Casey Rodarmor _ - :books: [`1f8023d13a39`](https://github.com/casey/intermodal/commit/1f8023d13a399e381176c20bbb6a71763b7c352a) Fix directory link in README - _Matt Boulanger _ - :sparkles: [`cb8b5a691945`](https://github.com/casey/intermodal/commit/cb8b5a691945b8108676f95d2888774263be8cc8) Partially implement BEP 53 - Fixes [#245](https://github.com/casey/intermodal/issues/245) - _strickinato _ - :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 _ diff --git a/README.md b/README.md index 9c42144..f591492 100644 --- 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)AUR | `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)AUR | `yay -S intermodal-bin` | +| [Arch Linux](https://www.archlinux.org) | [Yay](https://github.com/Jguer/yay) | [intermodal](https://aur.archlinux.org/packages/intermodal)AUR | `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/). diff --git a/bin/gen/config.yaml b/bin/gen/config.yaml index f41f060..d589454 100644 --- 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)AUR' + 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)AUR' + command: '`yay -S intermodal`' diff --git a/bin/gen/src/common.rs b/bin/gen/src/common.rs index 09be87a..f0d461a 100644 --- 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, }; diff --git a/bin/gen/src/config.rs b/bin/gen/src/config.rs index 7318a27..3a15701 100644 --- 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, pub(crate) examples: Vec, + pub(crate) packages: Vec, } impl Config { diff --git a/bin/gen/src/main.rs b/bin/gen/src/main.rs index e6e6790..189be3c 100644 --- 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() { diff --git a/bin/gen/src/opt.rs b/bin/gen/src/opt.rs index c94051a..44ec301 100644 --- 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'); diff --git a/bin/gen/src/package.rs b/bin/gen/src/package.rs new file mode 100644 index 0000000..9fa1dc0 --- /dev/null +++ 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, + ] + } +} diff --git a/bin/gen/src/readme.rs b/bin/gen/src/readme.rs index 53d0859..c4ecd91 100644 --- 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, } const HEADING_PATTERN: &str = "(?m)^(?P#+) (?P.*)$"; 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()), } } } diff --git a/bin/gen/src/row.rs b/bin/gen/src/row.rs new file mode 100644 index 0000000..d31d6e9 --- /dev/null +++ b/bin/gen/src/row.rs @@ -0,0 +1,5 @@ +pub(crate) trait Row { + fn header() -> &'static [&'static str]; + + fn entries(&self) -> Vec<&str>; +} diff --git a/bin/gen/src/table.rs b/bin/gen/src/table.rs new file mode 100644 index 0000000..924e36c --- /dev/null +++ b/bin/gen/src/table.rs @@ -0,0 +1,52 @@ +use crate::common::*; + +pub(crate) struct Table { + rows: Vec, +} + +impl Table { + pub(crate) fn new(rows: Vec) -> Table { + Table { rows } + } +} + +impl Display for Table { + 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, "|:{:-AUR | `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/).