docs: enable building rust API docs

Author: thunderbiscuit

.github/ISSUE_TEMPLATE/release.md

@@ -51,10 +51,15 @@ git push upstream v0.6.0
 ```
 14. - [ ] Trigger manual releases for both libraries (for Swift, go to the [bdk-swift](https://github.com/bitcoindevkit/bdk-swift) repository and trigger the workflow using `master`. Simply add the version number and tag name in the text fields when running the workflow manually. Note that the version number must not contain the `v`, i.e. `0.26.0`, but the tag will have it, i.e. `v0.26.0`). For Android, trigger the release workflow using the tag (not a branch).
 15. - [ ] Make sure the released libraries work and contain the artifacts you would expect.
-16. - [ ] Aggregate all the changelog notices from the PRs and add them to the changelog file. PR that.
-17. - [ ] Bump the version on master from `1.1.0-SNAPSHOT` to `1.2.0-SNAPSHOT` (Android) and `1.1.0-alpha.0` to `1.2.0-alpha.0` (Rust).
-18. - [ ] Apply changes to the release issue template if needed.
-19. - [ ] Make release on GitHub (generate auto release notes between the previous tag and the new one).
-20. - [ ] Build API docs for Android locally and PR the website to the bitcoindevkit.org repo.
-21. - [ ] Post in the announcement channel.
-22. - [ ] Tweet about the new release!
+16. - [ ] Build the Rust API docs and publish them to the repo's GitHub Pages.
+```shell
+cd bdk-ffi/
+just docs
+```
+17. - [ ] Aggregate all the changelog notices from the PRs and add them to the changelog file. PR that.
+18. - [ ] Bump the version on master from `1.1.0-SNAPSHOT` to `1.2.0-SNAPSHOT` (Android) and `1.1.0-alpha.0` to `1.2.0-alpha.0` (Rust).
+19. - [ ] Apply changes to the release issue template if needed.
+20. - [ ] Make release on GitHub (generate auto release notes between the previous tag and the new one).
+21. - [ ] Build API docs for Android locally and PR the website to the bitcoindevkit.org repo.
+22. - [ ] Post in the announcement channel.
+23. - [ ] Tweet about the new release!

bdk-ffi/justfile

@@ -13,3 +13,7 @@ check:
 
 test:
   cargo test
+
+# Build API documentation for gh-pages or local browsing
+docs:
+  bash scripts/build-docs.sh && bash scripts/deploy-docs.sh

bdk-ffi/scripts/build-docs.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# Rustdoc only emits module pages for publicly reachable modules. For the docs to
+# build correctly, we temporarily rewrite the top-level `mod foo;` lines into `pub mod foo;`.
+sed -i '' -E 's/^mod (bitcoin|descriptor|electrum|error|esplora|keys|kyoto|macros|store|tx_builder|types|wallet);$/pub mod \1;/' src/lib.rs
+
+# We always restore the original `src/lib.rs` on exit so the temporary visibility
+# change never sticks around after the docs build finishes.
+cleanup() {
+  sed -i '' -E 's/^pub mod (bitcoin|descriptor|electrum|error|esplora|keys|kyoto|macros|store|tx_builder|types|wallet);$/mod \1;/' src/lib.rs
+}
+trap cleanup EXIT
+
+# Build the docs
+rm -rf target/doc
+cargo doc --no-deps
+printf '%s\n' '<meta http-equiv="refresh" content="0; url=bdkffi/index.html">' > target/doc/index.html
+printf 'Documentation built at target/doc/\n'

bdk-ffi/scripts/deploy-docs.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+# Build the docs site and publish it to the gh-pages branch, which GitHub Pages
+# serves at https://bitcoindevkit.github.io/bdk-ffi/.
+
+set -euo pipefail
+
+cd ./target/doc/
+git init .
+git switch --create gh-pages
+git add .
+git commit --message "Deploy $(date +"%Y-%m-%d")"
+git remote add upstream git@github.com:bitcoindevkit/bdk-ffi.git
+git push upstream gh-pages --force
+cd ..