docs-toolchain

What this skill does

# Documentation Toolchain (mdBook + Dokka + rustdoc)

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

## Tool Selection

| Tool | Best for | Output |
|---|---|---|
| **mdBook** | Long-form prose docs (book/handbook style) | Static HTML site, searchable |
| **rustdoc** | Rust API reference (auto-generated from `///` comments) | docs.rs-style HTML |
| **Dokka** | Kotlin/JVM/KMP API reference | HTML or Markdown |
| **Showkase** | Compose UI component browser (interactive previews) | Embedded in app or live site |

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

```bash
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

```bash
mdbook init my-docs
cd my-docs
```

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

### Configuration

```toml
# 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)

```markdown
# 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

```bash
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

```toml
# 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

```rust
//! 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

```bash
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:

```bash
cargo test --doc
```

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

### Cargo.toml Metadata

```toml
[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

```bash
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

```kotlin
// 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

```kotlin
/**
 * 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

```bash
./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:

```kotlin
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

```kotlin
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