Fix release pipeline

.github/workflows/release.yml

@@ -28,12 +28,9 @@ jobs:
         if: ${{ !contains(matrix.target, 'windows') }}
       - run: sudo apt-get install musl-tools
         if: ${{ contains(matrix.target, 'linux-musl') }}
-      - shell: bash
-        id: build
-        run: |
-            OUTDIR="$(cargo build --locked --target '${{ matrix.target }}' ${{ matrix.cargo_opts }} --release --message-format=json-render-diagnostics |
-                jq -r 'select(.out_dir) | select(.package_id | startswith("mdcat ")) | .out_dir')"
-            echo "outdir=$OUTDIR" >>"$GITHUB_OUTPUT"
+      - run: cargo build --locked --target '${{ matrix.target }}' ${{ matrix.cargo_opts }} --release
+      - run: asciidoctor -b manpage -a reproducible mdcat.1.adoc
+        if: ${{ !contains(matrix.target, 'windows') }}
       - run: strip 'target/${{ matrix.target }}/release/mdcat'
         if: ${{ !contains(matrix.target, 'windows') }}
       - id: version
@@ -42,7 +39,7 @@ jobs:
           echo "version=$(cargo pkgid | cut -d'#' -f2 | cut -d: -f2)" >>"${GITHUB_OUTPUT}"
       - id: package
         shell: bash
-        run: ./scripts/package '${{ steps.version.outputs.version }}' '${{ matrix.target }}' '${{ steps.build.outputs.outdir }}'
+        run: ./scripts/package '${{ steps.version.outputs.version }}' '${{ matrix.target }}'
       - uses: actions/upload-artifact@v4
         with:
           name: ${{ steps.package.outputs.name }}

CHANGELOG.md

@@ -8,9 +8,23 @@ Use `cargo release` to create a new release.
 
 ## [Unreleased]
 
+### Added
+- mdcat now includes a `--completions` argument to generate shell completions for all major shells (see [GH-286]).
+
 ### Changed
 - Update dependencies.
 
+### Removed
+- mdcat now longer builds shell completions and man pages during compilation (see [GH-286]).
+  - Packagers now need to build the manpage explicitly during packaging.
+- Release artifacts no longer contain completions; use `mdcat --completions` to generate them instead (see [GH-286]).
+
+### Fixed
+- Restore binary release artifacts (see [GH-284])
+
+[GH-284]: https://github.com/swsnr/mdcat/issues/284
+[GH-286]: https://github.com/swsnr/mdcat/pull/286
+
 ## [2.2.0] – 2024-07-11
 
 ### Changed

Cargo.toml

@@ -20,6 +20,7 @@ static = ["mdcat-http-reqwest/rustls-tls-native-roots"]
 [dependencies]
 anyhow = { version = "1.0.86", default-features = false, features = ["std"] }
 clap = { version = "4.5.8", default-features = false, features = ["std", "derive", "help", "usage", "error-context"] }
+clap_complete = "4.5.7"
 human-panic = { version = "2.0.0", default-features = false, features = ["color"] }
 pulldown-cmark = { workspace = true, features = ['simd'] }
 reqwest = { workspace = true }
@@ -37,11 +38,6 @@ pulldown-cmark-mdcat = { version = "=2.2.0", path = "pulldown-cmark-mdcat" }
 [dev-dependencies]
 similar-asserts = { workspace = true }
 
-[build-dependencies]
-# To generate completions during build
-clap = { version = "4.5.8", features = ["derive"] }
-clap_complete = "4.5.7"
-
 [target.'cfg(windows)'.dependencies]
 anstyle-query = { version = "1.1.0", default-features = false }
 

README.md

@@ -73,19 +73,35 @@ Try `mdcat --help` or read the [mdcat(1)](./mdcat.1.adoc) manpage.
 
 Run `cargo build --release`.
 The resulting `mdcat` executable links against the system's SSL library, i.e. openssl on Linux.
+
 To build a self-contained executable use `cargo build --features=static`; the resulting executable uses a pure Rust SSL implementation.
 It still uses the system's CA roots however.
 
-The build process also generates the following additional files in `$OUT_DIR`:
+## Packaging
+
+When packaging `mdcat` you may wish to include the following additional artifacts:
+
+- A symlink or hardlink from `mdless` to `mdcat` (see above).
+- Shell completions for relevant shells, by invoking `mdcat --completions` after building, e.g.
 
-* Completions for Bash, Zsh, Fish, and Powershell, for both `mdcat` and `mdless`, in `completions` sub-directory.
-* A `mdcat.1` manpage, build from `mdcat.1.adoc` with the `asciidoctor` command from [AsciiDoctor].
-  If `asciidoctor` is not found the build script prints a warning.
+  ```console
+  $ mdcat --completions fish > /usr/share/fish/vendor_completions.d/mdcat.fish
+  $ mdcat --completions bash > /usr/share/bash-completion/completions/mdcat
+  $ mdcat --completions zsh > /usr/share/zsh/site-functions/_mdcat
+  # Same for mdless if you include it
+  $ mdless --completions fish > /usr/share/fish/vendor_completions.d/mdless.fish
+  $ mdless --completions bash > /usr/share/bash-completion/completions/mdless
+  $ mdless --completions zsh > /usr/share/zsh/site-functions/_mdless
+  ```
 
-These additional artifacts are included in the release builds.
-If you package mdcat you may want to include these files too.
+- A build of the man page `mdcat.1.adoc`, using [AsciiDoctor]:
 
-You may also want to include an `mdless` link to `mdcat` (see above).
+  ```console
+  $ asciidoctor -b manpage -a reproducible -o /usr/share/man/man1/mdcat.1 mdcat.1.adoc
+  $ gzip /usr/share/man/man1/mdcat.1
+  # If you include a mdless as above, you may also want to support man mdless
+  $ ln -s mdcat.1.gz /usr/share/man/man1/mdless.1.gz
+  ```
 
 [AsciiDoctor]: https://asciidoctor.org/
 

mdcat.1.adoc

@@ -115,6 +115,11 @@ This is the default when run as `mdcat`.
 --detect-terminal::
     Detect the terminal program, print its name, and exit.
 
+--completions=_SHELL_::
+    Generate completions for _SHELL_ to standard output and exit.
+
+    _SHELL_ can be one of `bash`, `zsh`, `fish`, `powershell`, or `elvish`.
+
 -h::
 --help::
     Show a help message to the user and exit.

scripts/package

@@ -9,7 +9,6 @@ set -exuo pipefail
 
 VERSION="$1"
 TARGET="$2"
-OUTDIR="$3"
 
 ARCHIVE_NAME="mdcat-${VERSION}-${TARGET}"
 
@@ -19,8 +18,7 @@ package_windows() {
     mv LICENSE LICENSE.txt
     7z a "${archive_file}" \
         "./target/${TARGET}/release/mdcat.exe" \
-        ./README.md ./CHANGELOG.md ./LICENSE.txt ./mdcat.1.adoc \
-        "${OUTDIR}/completions"
+        ./README.md ./CHANGELOG.md ./LICENSE.txt ./mdcat.1.adoc
     if [[ -n "${GITHUB_OUTPUT:-}" ]]; then
         echo "file=${archive_file}" >>"${GITHUB_OUTPUT}"
         echo "name=${ARCHIVE_NAME}.zip" >>"${GITHUB_OUTPUT}"
@@ -38,7 +36,7 @@ package_unix() {
     cp -r \
         README.md CHANGELOG.md LICENSE \
         "target/${TARGET}/release/mdcat" \
-        "${OUTDIR}/mdcat.1" "${OUTDIR}/completions" \
+        "mdcat.1" \
         "${pkg_dir}/${ARCHIVE_NAME}"
     tar -czf "${PWD}/${archive_file}" -C "${pkg_dir}" "${ARCHIVE_NAME}"
     echo "file=${archive_file}" >>"${GITHUB_OUTPUT}"

src/args.rs

@@ -5,6 +5,7 @@
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 use clap::ValueHint;
+use clap_complete::Shell;
 
 fn after_help() -> &'static str {
     "See 'man 1 mdcat' for more information.
@@ -61,7 +62,6 @@ pub enum Command {
 }
 
 impl Command {
-    #[allow(dead_code)]
     pub fn paginate(&self) -> bool {
         match *self {
             // In both cases look at the option indicating the non-default
@@ -107,6 +107,9 @@ pub struct CommonArgs {
     /// Skip terminal detection and only use ANSI formatting.
     #[arg(long = "ansi", conflicts_with = "no_colour")]
     pub ansi_only: bool,
+    /// Generate completions for a shell to standard output and exit.
+    #[arg(long)]
+    pub completions: Option<Shell>,
 }
 
 /// What resources mdcat may access.

src/main.rs

@@ -9,7 +9,8 @@
 
 //! Show CommonMark documents on TTYs.
 
-use clap::Parser;
+use clap::{CommandFactory, Parser};
+use clap_complete::generate;
 use mdcat::{create_resource_handler, process_file};
 use pulldown_cmark_mdcat::terminal::{TerminalProgram, TerminalSize};
 use pulldown_cmark_mdcat::{Settings, Theme};
@@ -41,6 +42,17 @@ fn main() {
     let args = Args::parse().command;
     event!(target: "mdcat::main", Level::TRACE, ?args, "mdcat arguments");
 
+    if let Some(shell) = args.completions {
+        let binary = match args {
+            mdcat::args::Command::Mdcat { .. } => "mdcat",
+            mdcat::args::Command::Mdless { .. } => "mdless",
+        };
+        let mut command = Args::command();
+        let subcommand = command.find_subcommand_mut(binary).unwrap();
+        generate(shell, subcommand, binary, &mut std::io::stdout());
+        std::process::exit(0);
+    }
+
     let terminal = if args.no_colour {
         TerminalProgram::Dumb
     } else if args.paginate() || args.ansi_only {