Docs Toolchain

Documentation Toolchain (mdBook + Dokka + rustdoc)

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: mdbook, dokka, or rustdoc.

Tool Selection

For BHODL-style multi-language project (Rust core + Kotlin/Swift mobile + Compose UI), use all four — each auto-targets its language.

mdBook — Prose Documentation

Used by Bitcoin Core docs, The Rust Book, RustNomicon, BDK book.

Install

cargo install mdbook

# Or via binstall (faster)
cargo binstall mdbook

# Plugins (popular)
cargo install mdbook-mermaid           # Mermaid diagrams
cargo install mdbook-toc               # auto table of contents
cargo install mdbook-linkcheck         # validate links
cargo install mdbook-katex             # LaTeX math rendering

Initialize

mdbook init my-docs
cd my-docs

Creates:

my-docs/
├── book.toml
└── src/
    ├── SUMMARY.md           # nav structure
    ├── chapter_1.md
    └── README.md

Configuration

# book.toml
[book]
authors = ["BHODL Team"]
language = "en"
multilingual = false
src = "src"
title = "BHODL Handbook"
description = "Self-custodial Bitcoin wallet handbook"

[output.html]
default-theme = "light"
preferred-dark-theme = "navy"
git-repository-url = "https://github.com/bhodl/bhodl"
git-repository-icon = "fa-github"
edit-url-template = "https://github.com/bhodl/bhodl/edit/main/docs/{path}"
site-url = "/bhodl/"
cname = "docs.bhodl.app"

[output.html.search]
enable = true
limit-results = 30
heading-split-level = 2

[output.html.fold]
enable = true
level = 1

[preprocessor.mermaid]
command = "mdbook-mermaid"

[preprocessor.toc]
command = "mdbook-toc"
renderer = ["html"]

[output.linkcheck]
follow-web-links = false
warning-policy = "error"

SUMMARY.md (Navigation)

# Summary

[Introduction](README.md)

# User Guide
- [Quick Start](user/quick-start.md)
- [Create a Wallet](user/create-wallet.md)
- [Backup & Recovery](user/backup.md)
- [Send & Receive](user/send-receive.md)

# Architecture
- [Overview](arch/overview.md)
- [Bitcoin Core Layer](arch/bitcoin.md)
- [Lightning Layer](arch/lightning.md)
- [FFI & Mobile](arch/ffi.md)

# Developer Guide
- [Build From Source](dev/build.md)
- [Reproducible Build](dev/reproducible.md)
- [Contributing](dev/contributing.md)

# Reference
- [API](reference/api.md)
- [Configuration](reference/config.md)

[Glossary](glossary.md)
[Changelog](changelog.md)

Build & Serve

mdbook build                  # generates book/ directory
mdbook serve                  # live reload at localhost:3000
mdbook test                   # run code blocks as tests (Rust by default)
mdbook clean

Custom CSS / JS

# book.toml
[output.html]
additional-css = ["theme/bhodl.css"]
additional-js = ["theme/copy-code.js"]

For brand consistency, override mdBook's default theme with BHODL colors.

rustdoc — Rust API Documentation

//! Crate-level docs go here.
//!
//! # Examples
//!
//! ```
//! let wallet = bhodl::Wallet::new("abandon abandon ...");
//! ```

/// Creates a new wallet from a BIP39 mnemonic.
///
/// # Arguments
/// * `mnemonic` - The BIP39 seed phrase (12 or 24 words)
///
/// # Errors
/// Returns [`WalletError::InvalidMnemonic`] if the mnemonic is malformed.
///
/// # Example
/// ```
/// use bhodl::Wallet;
/// let wallet = Wallet::new("abandon abandon abandon ...")?;
/// # Ok::<(), bhodl::WalletError>(())
/// ```
pub fn new(mnemonic: &str) -> Result<Wallet, WalletError> {
    // ...
}

Build

cargo doc                     # build docs for current crate
cargo doc --open              # build and open in browser
cargo doc --no-deps           # only your crate, not deps
cargo doc --workspace         # all workspace crates
cargo doc --document-private-items

Output in target/doc/<crate_name>/.

Doc Tests

Code blocks in /// comments are run as tests:

cargo test --doc

Catches docs that drift out of sync with code. Use # prefix to hide setup lines.

Cargo.toml Metadata

[package]
name = "bhodl"
version = "0.1.0"
authors = ["BHODL Team"]
description = "Self-custodial Bitcoin wallet"
documentation = "https://docs.rs/bhodl"
repository = "https://github.com/bhodl/bhodl"
keywords = ["bitcoin", "wallet", "lightning"]
categories = ["cryptography"]

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]

For docs.rs publishing: ensure Cargo.toml metadata is rich. The site auto-builds on each crates.io release.

Publish to docs.rs

cargo publish                 # auto-triggers docs.rs build

For private projects: host rustdoc output on GitHub Pages.

Dokka — Kotlin API Documentation

For KMP / Android / JVM Kotlin code.

Setup

// build.gradle.kts (root)
plugins {
    id("org.jetbrains.dokka") version "1.9.20"
}

allprojects {
    apply(plugin = "org.jetbrains.dokka")
}

// Per module
tasks.dokkaHtml.configure {
    outputDirectory.set(layout.buildDirectory.dir("dokka"))
    dokkaSourceSets.configureEach {
        documentedVisibilities.set(setOf(Visibility.PUBLIC, Visibility.PROTECTED))
        skipDeprecated.set(false)
        suppressInheritedMembers.set(true)
        sourceLink {
            localDirectory.set(file("src"))
            remoteUrl.set(URL("https://github.com/bhodl/shared/tree/main/src"))
            remoteLineSuffix.set("#L")
        }
        externalDocumentationLink {
            url.set(URL("https://kotlinlang.org/api/latest/jvm/stdlib/"))
        }
    }
}

tasks.dokkaHtmlMultiModule.configure {
    outputDirectory.set(rootDir.resolve("docs/api"))
}

KDoc Syntax

/**
 * Manages a Bitcoin wallet with BIP39 backup.
 *
 * @property network The Bitcoin network (mainnet, testnet, etc.)
 * @constructor Creates a wallet from a mnemonic.
 *
 * @sample WalletSamples.basicUsage
 */
class Wallet(
    val network: Network,
    mnemonic: String,
) {
    /**
     * Returns the next unused receive address.
     *
     * @param index Address index in the derivation path. Defaults to next unused.
     * @return BIP-encoded address.
     * @throws WalletException if descriptor is invalid.
     */
    fun nextAddress(index: Int? = null): String { /* ... */ }
}

Build

./gradlew dokkaHtml                              # one module HTML
./gradlew dokkaHtmlMultiModule                   # combined for all modules
./gradlew dokkaGfm                                # GitHub-flavored Markdown output
./gradlew dokkaJavadoc                            # legacy Javadoc-style HTML

Multiplatform Source Sets

Dokka understands KMP source sets — generates per-platform docs:

dokkaSourceSets {
    named("commonMain") {
        displayName.set("Common")
    }
    named("androidMain") {
        displayName.set("Android")
        platform.set(org.jetbrains.dokka.Platform.jvm)
    }
    named("iosMain") {
        displayName.set("iOS")
        platform.set(org.jetbrains.dokka.Platform.native)
    }
}

Output shows expect/actual relationships, per-platform availability.

Publishing

publishing {
    publications.withType<MavenPublication> {
        artifact(tasks.dokkaJar.get())
    }
}

tasks.register<Jar>("dokkaJar") {
    dependsOn(tasks.dokkaHtml)
    archiveClassifier.set("javadoc")
    from(tasks.dokkaHtml.get().outputDirectory)
}

For Maven Central: include dokkaJar artifact alongside JAR.

Showkase — Compose Component Browser

Auto-discovers @Preview composables and renders them in a browsable UI (in-app or static site).

// build.gradle.kts
implementation("com.airbnb.android:showkase:1.0.4")
ksp("com.airbnb.android:showkase-processor:1.0.4")

@ShowkaseRoot
class MyShowkaseRootModule : ShowkaseRootModule

// Annotate composables for browser
@ShowkaseComposable(name = "WalletItem", group = "Wallet")
@Composable
fun WalletItemPreview() {
    BhodlTheme {
        WalletItem(testWallet())
    }
}

// In MainActivity (debug build only)
@Composable
fun ShowkaseEntry() {
    val context = LocalContext.current
    Button(onClick = {
        context.startActivity(Showkase.getBrowserIntent(context))
    }) { Text("Component browser") }
}

For static site export (in CI):

// Use showkase-screenshot-testing or manual export

Pair with Paparazzi for snapshots — see testing/compose-snapshot.

Combining All Tools — Project Layout

bhodl/
├── docs/
│   ├── book.toml                                # mdBook config
│   └── src/
│       ├── SUMMARY.md
│       ├── user/...
│       ├── arch/...
│       └── reference/
│           ├── rust-api.md                       # links to rustdoc
│           └── kotlin-api.md                     # links to Dokka
├── crates/
│   └── bhodl-core/
│       ├── Cargo.toml
│       └── src/                                  # rustdoc auto-generated
├── shared/                                       # KMP module (Dokka auto-generated)
│   └── src/
└── .github/workflows/
    └── docs.yml                                  # publish all to GitHub Pages

Single Site Deployment

Combine all outputs into one site:

docs-site/
├── /                                            # mdBook output
├── /api/rust/                                    # cargo doc output
├── /api/kotlin/                                  # Dokka multiModule output
└── /components/                                  # Showkase static export

Cross-link from book chapters to API docs:

For details see the [`Wallet` Rust API](api/rust/bhodl/struct.Wallet.html)
or the [Kotlin API](api/kotlin/-shared/com.bhodl/-wallet/).

CI Publication — GitHub Pages

# .github/workflows/docs.yml
name: Publish docs

on:
  push:
    branches: [main]
  release:
    types: [published]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - uses: actions/setup-java@v4
        with: { java-version: '17', distribution: 'temurin' }
      - uses: gradle/actions/setup-gradle@v4

      - name: Install mdBook
        run: cargo binstall -y mdbook mdbook-mermaid mdbook-toc mdbook-linkcheck

      - name: Build mdBook
        run: cd docs && mdbook build

      - name: Build rustdoc
        run: cargo doc --workspace --no-deps --all-features
        env:
          RUSTDOCFLAGS: "-D warnings"

      - name: Build Dokka
        run: ./gradlew dokkaHtmlMultiModule

      - name: Combine output
        run: |
          mkdir -p public
          cp -r docs/book/* public/
          mkdir -p public/api/rust
          cp -r target/doc/* public/api/rust/
          mkdir -p public/api/kotlin
          cp -r docs/api/* public/api/kotlin/

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          cname: docs.bhodl.app

Versioning Strategy

For each release, archive docs:

/                            # latest stable
/v0.1.0/                      # historical
/v0.2.0/
/dev/                         # rolling main branch

Use mike (mkdocs versioning) or roll-your-own with workflow that copies to versioned subdir.

For Rust: docs.rs handles this automatically per crate version.

For Kotlin: Dokka's moduleVersion parameter sets version label; archive output dirs.

Custom Branding

mdBook theme override:

docs/theme/
├── index.hbs                 # custom HTML template
├── bhodl.css                 # custom CSS
└── favicon.svg

[output.html]
theme = "theme"
preferred-dark-theme = "ayu"
additional-css = ["theme/bhodl.css"]

Inline Doc Linting

For consistent doc style, integrate with linters:

# Cargo.toml
[lints.rust]
missing_docs = "warn"

[lints.rustdoc]
broken_intra_doc_links = "deny"
private_doc_tests = "warn"

// detekt.yml
documentation:
  CommentOverPrivateFunction: { active: true }
  EndOfSentenceFormat: { active: true }
  UndocumentedPublicClass: { active: true, searchInNestedClass: true }
  UndocumentedPublicFunction: { active: true }
  UndocumentedPublicProperty: { active: true }

Anti-Patterns

Troubleshooting

When NOT to Use This Skill