feat: Render top-level docs using mdbook

Rely on mdbook to render top-level documentation in a concise manner.
Using the `build-book` just recipe the mdbook (including adhoc addition
of js requirements for nermaid graphs) is built from a preselected list
of documentation files.
Afterwards all Rust documentation is collected in a `rustdoc`
subdirectory of the shared documentation output directory.

The `watch-book` and `serve-book` just recipes enable a worklow in which
relevant files are watched and the output dir is continuously served
using an adhoc webserver.

Fixes: #124


Signed-off-by: David Runge <dvzrv@archlinux.org>

.codespellrc

 [codespell]
-skip = .cargo,.git,target,.env,Cargo.lock,*.asc
+skip = .cargo,.git,target,.env,Cargo.lock,*.asc,output,*.js
 ignore-words-list = crate,passt,ser

.env

 # Contains project specific variables
 
 # List of packages required specifically by this project
-PACMAN_PACKAGES="acl cargo-deny cargo-machete cargo-nextest clang cmake cocogitto codespell cpio edk2-ovmf erofs-utils git jq just lychee make mkosi mold mtools openssl pkgconf podman qemu release-plz reuse ripgrep rsop rustup rust-script sbsigntools sequoia-sq shellcheck swtpm systemd-ukify tangler zstd"
+PACMAN_PACKAGES="acl cargo-deny cargo-machete cargo-nextest clang cmake cocogitto codespell cpio edk2-ovmf erofs-utils git jq just lychee make mdbook mdbook-mermaid miniserve mkosi mold mtools openssl pkgconf podman qemu release-plz reuse ripgrep rsop rustup rust-script sbsigntools sequoia-sq shellcheck swtpm systemd-ukify tangler watchexec zstd"

.gitignore

 # GnuPG only supports binary keyrings, because reasons, but we don't want to add binary keyrings to the repo
+output/
+resources/docs/*.js
 resources/mkosi/signstar/mkosi.extra/usr/lib/systemd/import-pubring.gpg
 resources/mkosi/signstar/mkosi.output
 resources/mkosi/signstar/mkosi.profiles/local-testing/mkosi.extra/usr/local/bin/

justfile

@@ -7,6 +7,10 @@ set dotenv-load := true
 
 ignored := "false"
 
+# The output directory for documentation artifacts
+
+output_dir := "output"
+
 # Runs all checks and tests. Since this is the first recipe it is run by default.
 run-pre-commit-hook: check test
 
@@ -556,3 +560,35 @@ build-test-image openpgp_signing_key signing_key="resources/mkosi/signstar/mkosi
 run-image mkosi_options="" qemu_options="":
     just ensure-command mkosi
     mkosi -C resources/mkosi/signstar/ {{ mkosi_options }} qemu {{ qemu_options }}
+
+# Builds the documentation book using mdbook and stages all necessary rustdocs alongside
+build-book: docs
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    just ensure-command mdbook mdbook-mermaid
+
+    readonly target_dir="${CARGO_TARGET_DIR:-$PWD/target}"
+    readonly output_dir="{{ output_dir }}"
+    readonly rustdoc_dir="$output_dir/docs/rustdoc/"
+    mapfile -t workspace_members < <(just get-workspace-members 2>/dev/null)
+
+    mdbook-mermaid install resources/docs/
+    mdbook build resources/docs/
+
+    # move rust docs to their own namespaced dir
+    mkdir -p "$rustdoc_dir"
+    for name in "${workspace_members[@]}"; do
+        cp -r "$target_dir/doc/${name//-/_}" "$rustdoc_dir"
+    done
+
+# Serves the documentation book using miniserve
+serve-book: build-book
+    just ensure-command miniserve
+    miniserve --index=index.html {{ output_dir }}/docs
+
+# Watches the documentation book contents and rebuilds on change using mdbook (useful for development)
+watch-book:
+    just ensure-command watchexec
+    watchexec --exts md,toml,js --delay-run 5s :w
+    just build-book

resources/docs/book.toml

+[book]
+authors = [
+    "David Runge",
+    "Wiktor Kwapisiewicz",
+]
+language = "en"
+multilingual = false
+src = "src"
+title = "Signstar"
+
+[build]
+build-dir = "../../output/docs"
+
+[preprocessor]
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
+
+[output]
+
+[output.html]
+additional-js = ["mermaid.min.js", "mermaid-init.js"]

resources/docs/src/CONTRIBUTING.md

+../../../CONTRIBUTING.md
\ No newline at end of file

resources/docs/src/README.md

+../../../README.md
\ No newline at end of file

resources/docs/src/SUMMARY.md

+# Summary
+
+[Introduction](./README.md)
+
+# Components
+
+- [nethsm](./nethsm/README.md)
+  - [CHANGELOG](./nethsm/CHANGELOG.md)
+- [nethsm-backup](./nethsm-backup/README.md)
+- [nethsm-cli](./nethsm-cli/README.md)
+  - [CHANGELOG](./nethsm-cli/CHANGELOG.md)
+- [nethsm-config](./nethsm-config/README.md)
+  - [CHANGELOG](./nethsm-config/CHANGELOG.md)
+- [nethsm-tests](./nethsm-tests/README.md)
+  - [CHANGELOG](./nethsm-tests/CHANGELOG.md)
+- [signstar-configure-build](./signstar-configure-build/README.md)
+  - [CHANGELOG](./signstar-configure-build/CHANGELOG.md)
+
+# Architecture
+
+- [Design](./architecture/design.md)
+- [Evaluated Setups](./architecture/evaluated-setups.md)
+- [Previous Setup](./architecture/previous-setup.md)
+
+# Development
+
+- [Contributing Guidelines](./CONTRIBUTING.md)

resources/docs/src/architecture/design.md

+../../design.md
\ No newline at end of file

resources/docs/src/architecture/evaluated-setups.md

+../../evaluated-setups.md
\ No newline at end of file

resources/docs/src/architecture/previous-setup.md

+../../previous-setup.md
\ No newline at end of file

resources/docs/src/nethsm-backup/README.md

+../../../../nethsm-backup/README.md
\ No newline at end of file

resources/docs/src/nethsm-cli/CHANGELOG.md

+../../../../nethsm-cli/CHANGELOG.md
\ No newline at end of file

resources/docs/src/nethsm-cli/README.md

+../../../../nethsm-cli/README.md
\ No newline at end of file

resources/docs/src/nethsm-config/CHANGELOG.md

+../../../../nethsm-config/CHANGELOG.md
\ No newline at end of file

resources/docs/src/nethsm-config/README.md

+../../../../nethsm-config/README.md
\ No newline at end of file

resources/docs/src/nethsm-tests/CHANGELOG.md

+../../../../nethsm-tests/CHANGELOG.md
\ No newline at end of file

resources/docs/src/nethsm-tests/README.md

+../../../../nethsm-tests/README.md
\ No newline at end of file

resources/docs/src/nethsm/CHANGELOG.md

+../../../../nethsm/CHANGELOG.md
\ No newline at end of file

resources/docs/src/nethsm/README.md

+../../../../nethsm/README.md
\ No newline at end of file