From b68100b20e1ea18bf3a1ca398d7af986df26f7fa Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Wed, 7 Jan 2026 13:01:30 -0500
Subject: [PATCH] docs: Publish rustdoc for internal crates alongside mdbook

The docs workflow now also generates rustdoc for all workspace crates
and publishes them as a subdirectory of the main documentation site.
This makes internal API documentation available at
bootc-dev.github.io/bootc/internals.html with links to each crate.

Note this required switching the docs container to CentOS Stream 10 for newer Rust (1.91).

Assisted-by: OpenCode (Opus 4.5)
Signed-off-by: Colin Walters <walters@verbum.org>
---
 Justfile               |  4 ++--
 docs/Dockerfile.mdbook | 30 +++++++++++++-----------------
 docs/src/SUMMARY.md    |  4 ++++
 docs/src/internals.md  | 24 ++++++++++++++++++++++++
 4 files changed, 43 insertions(+), 19 deletions(-)
 create mode 100644 docs/src/internals.md

diff --git a/Justfile b/Justfile
index a8172c1d..a364efbc 100644
--- a/Justfile
+++ b/Justfile
@@ -233,7 +233,7 @@ pullspec-for-os TYPE NAME:
     @jq -r --arg v "{{NAME}}" '."{{TYPE}}"[$v]' < hack/os-image-map.json
 
 build-mdbook:
-    cd docs && podman build {{base_buildargs}} -t localhost/bootc-mdbook -f Dockerfile.mdbook
+    podman build {{generic_buildargs}} -t localhost/bootc-mdbook -f docs/Dockerfile.mdbook .
 
 # Generate the rendered HTML to the target DIR directory
 build-mdbook-to DIR: build-mdbook
@@ -241,7 +241,7 @@ build-mdbook-to DIR: build-mdbook
     set -xeuo pipefail
     # Create a temporary container to extract the built docs
     container_id=$(podman create localhost/bootc-mdbook)
-    podman cp ${container_id}:/src/book {{DIR}}
+    podman cp ${container_id}:/src/docs/book {{DIR}}
     podman rm -f ${container_id}
 
 mdbook-serve: build-mdbook
diff --git a/docs/Dockerfile.mdbook b/docs/Dockerfile.mdbook
index 3020eeb5..f0d67fdf 100644
--- a/docs/Dockerfile.mdbook
+++ b/docs/Dockerfile.mdbook
@@ -1,33 +1,29 @@
-FROM registry.access.redhat.com/ubi10/ubi:latest
-# An intermediate layer which caches the RPMS
+FROM ghcr.io/bootc-dev/devenv-c10s:latest
+USER root
+# Install mdbook tooling via cargo-binstall
 RUN <<EORUN
 set -xeuo pipefail
-dnf -y install cargo rust jq unzip
-dnf clean all
-EORUN
-# See main Dockerfile for rust caching
-RUN --mount=type=cache,target=/src/target --mount=type=cache,target=/var/roothome <<EORUN
-set -xeuo pipefail
-
-# Bootstrap cargo-binstall
-export PATH=$HOME/.cargo/bin:$PATH
 curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash
-
 deps=(mdbook@0.4.52 
       mdbook-mermaid@0.16.0 
       mdbook-linkcheck@0.7.7
       mdbook_header_footer@0.0.3)
-cargo binstall --no-confirm ${deps[@]}
-mv ~/.cargo/bin/* /usr/bin/
-
+cargo binstall --no-confirm --root /usr/local ${deps[@]}
 EORUN
 # And now actually build the docs
 WORKDIR /src
 COPY . /src
-RUN <<EORUN
+RUN --mount=type=cache,target=/src/target <<EORUN
 set -xeuo pipefail
+# Build rustdoc for internal crates
+cargo doc --workspace --no-deps --document-private-items
+# Build mdbook
+cd docs
 mdbook-mermaid install .
 mdbook build
+# Copy rustdoc into mdbook output
+cp -r /src/target/doc book/internals
 EORUN
-CMD ["mdbook", "serve", "-n", "0.0.0.0", "-p", "8000"]
+WORKDIR /src/docs/book
+CMD ["python3", "-m", "http.server", "8000", "--bind", "0.0.0.0"]
 EXPOSE 8000
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index c12144d3..9e23b00b 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -70,3 +70,7 @@
 - [Relationship with other projects](relationships.md)
 - [Relationship with OCI artifacs](relationship-oci-artifacts.md)
 - [Relationship with systemd "particles"](relationship-particles.md)
+
+# Development
+
+- [Internals (rustdoc)](internals.md)
diff --git a/docs/src/internals.md b/docs/src/internals.md
new file mode 100644
index 00000000..64e19fdf
--- /dev/null
+++ b/docs/src/internals.md
@@ -0,0 +1,24 @@
+# Internals (rustdoc)
+
+This section provides rustdoc API documentation for bootc's internal crates.
+These are intended for developers working on bootc itself, not for external consumption.
+
+## Core crates
+
+- [bootc-lib](internals/bootc_lib/index.html) - Core bootc implementation
+- [bootc](internals/bootc/index.html) - CLI frontend
+
+## Supporting crates
+
+- [ostree-ext](internals/ostree_ext/index.html) - Extension APIs for OSTree
+- [bootc-mount](internals/bootc_mount/index.html) - Internal mount utilities
+- [bootc-kernel-cmdline](internals/bootc_kernel_cmdline/index.html) - Kernel command line parsing
+- [bootc-initramfs-setup](internals/bootc_initramfs_setup/index.html) - Initramfs setup code
+- [etc-merge](internals/etc_merge/index.html) - /etc merge handling
+
+## Utility crates
+
+- [bootc-internal-utils](internals/bootc_internal_utils/index.html) - Internal utilities
+- [bootc-internal-blockdev](internals/bootc_internal_blockdev/index.html) - Block device handling
+- [bootc-sysusers](internals/bootc_sysusers/index.html) - systemd-sysusers implementation
+- [bootc-tmpfiles](internals/bootc_tmpfiles/index.html) - systemd-tmpfiles implementation