feat: rust doc

Run cargo doc against the workspace - great with the
deny(broken_intra_doc_links) lint.

Author: domodwyer

.pre-commit-hooks.yaml

@@ -102,6 +102,15 @@
   minimum_pre_commit_version: 0.15.0
   description: 'Run cargo fmt in the repo root'
 
+- id: rust-doc
+  name: 'Cargo doc'
+  entry: run-rust-doc.sh
+  language: 'script'
+  files: \.rs$
+  pass_filenames: false
+  minimum_pre_commit_version: 0.15.0
+  description: 'Run cargo doc against public & private items'
+
 - id: r-stylr
   name: 'Format with stylr'
   entry: run-r-stylr.R

README.md

@@ -16,6 +16,7 @@ Hooks:
 * `rust-clippy`: runs `cargo clippy` lints in the repo root
 * `rust-test`: runs `cargo test` at the repo root, includes all targets/features/examples/benches
 * `rust-fmt`: runs `cargo fmt --all`
+* `rust-doc`: runs `cargo doc` against the workspace - great for linting [intra-doc links]
 * `r-stylr`: runs [`stylr`] to format R code
 * `r-lintr`: static analysis of R code with [`lintr`]
 * `buf-lint`: runs [`buf`] lints against protobuf files
@@ -78,6 +79,9 @@ repos:
       - id: rust-fmt
         stages: [commit, push]
 
+      - id: rust-doc
+        stages: [push]
+      
       - id: r-stylr
         stages: [commit, push]
 
@@ -141,4 +145,5 @@ When adding new hooks you can run `pre-commit try-repo .` for a quick syntax che
 [`post-checkout`]: https://git-scm.com/docs/githooks#_post_checkout
 [`stylr`]: https://styler.r-lib.org/
 [`lintr`]: https://github.com/jimhester/lintr
-[`buf`]: https://buf.build/
+[`buf`]: https://buf.build/
+[intra-doc links]: https://doc.rust-lang.org/rustdoc/lints.html#broken_intra_doc_links  

run-rust-doc.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# Requires:
+#![deny(broken_intra_doc_links)]
+cargo doc --no-deps --all-features --workspace --document-private-items