Get the reference docs generating

[jhaaaa]

Introduction 📟

The SDK reference docs for this repo stopped generating in Dec 2025. This PR enables them to generate again.

Purpose ℹ️

Enable SDK reference docs to start generating again.

Scope 🔭

• Updates .github/workflows/docs.yml to enable reference docs to start generating again.
• Specifically, the PR switches from using Jazzy to DocC for ref doc generation. Per Claude Code: Jazzy relies on SourceKit for module discovery, which fails on Swift packages with binary framework dependencies. Since this project uses LibXMTPSwiftFFI.xcframework (the Rust FFI bindings), Jazzy cannot resolve the XMTPiOS module and documentation generation fails silently. DocC is Apple's official documentation tool, is already configured as a dependency in Package.swift (swift-docc-plugin), and works seamlessly with binary targets. This change also simplifies the CI workflow by removing the Ruby/Bundler setup previously required for Jazzy.

Is there a requirement that we use Jazzy?

[claude]

Claude finished @jhaaaa's task —— View job

---

Code Review Complete ✅

Tasks

• Read and analyze changed files
• Review workflow changes (.github/workflows/docs.yml)
• Review .gitignore changes
• Check for security concerns
• Check for potential bugs or issues
• Evaluate performance considerations
• Assess test coverage implications
• Provide comprehensive feedback

---

Review Feedback

This PR successfully modernizes the documentation generation workflow from Jazzy to DocC. The changes are well-reasoned and address a real compatibility issue with binary frameworks. Overall, this is a solid improvement with a few minor suggestions below.

✅ Strengths

1. Well-justified change: The switch from Jazzy to DocC is appropriate given the binary framework dependency issue
2. Simplification: Removes Ruby/Bundler dependencies, reducing CI complexity and maintenance burden
3. Official tooling: DocC is Apple's official documentation tool and already configured in Package.swift:21
4. Cleaner workflow: Removed unnecessary update-package job and branch trigger (update_swift_rust)
5. Proper .gitignore: Added generated docs directories to prevent accidental commits

📝 Suggestions & Observations

1. Missing Error Handling (Minor)
.github/workflows/docs.yml:27
The swift build step doesn't specify any error handling. Consider adding set -e or checking build success explicitly:

- name: Build Swift package
  run: |
    set -e
    swift build

2. Documentation Generation May Fail Silently (Low Priority)
.github/workflows/docs.yml:29-36
If documentation generation fails, the workflow may continue. Consider adding explicit error checking:

- name: Generate documentation
  run: |
    set -e
    swift package --allow-writing-to-directory ./docs \
      generate-documentation \
      --target XMTPiOS \
      --output-path ./docs \
      --transform-for-static-hosting \
      --hosting-base-path xmtp-ios

3. Runner Version Change (Observation)
.github/workflows/docs.yml:22
Changed from macos-13 to macos-latest. This is generally fine, but be aware:

• macos-latest currently points to macOS 14 (as of 2026)
• Future updates to macos-latest could introduce breaking changes
• Consider pinning to specific version (e.g., macos-14) for stability

4. Removed Branch Trigger (Question)
.github/workflows/docs.yml:5
Removed update_swift_rust from branch triggers. Was this branch deprecated? Just confirming this was intentional.

5. Test Coverage (Observation)
There's no automated test to verify docs generation succeeds. Consider:

• Running the workflow on this PR branch before merging
• Adding a test job that validates docs were generated (checks for existence of key files)
• Documenting manual testing steps in the PR description

🔒 Security Assessment

✅ No security concerns identified:

• Removed third-party dependencies (Ruby gems) reduces attack surface
• Using official GitHub Actions with version pins
• No credential or secret handling
• Proper permissions configuration (read-only contents, write-only pages)

⚡ Performance Considerations

✅ Performance improved:

• Eliminates Ruby/Bundler setup time (~30-60 seconds)
• Removes gem caching complexity
• Simpler dependency chain (no needs: update-package)
• DocC is generally faster than Jazzy for Swift packages

🧪 Test Coverage Implications

⚠️ Action Required:
Since this changes the documentation generation system entirely, you should:

1. Manually test the workflow on this branch before merging
2. Verify the generated docs render correctly on GitHub Pages
3. Check that all public APIs are documented in the output
4. Compare output with previous Jazzy docs to ensure no regression

You can test this by:

• Manually triggering the workflow on this branch via workflow_dispatch
• Or waiting for the workflow to run on the PR branch push

📋 Final Recommendation

APPROVE with minor suggestions. The changes are sound and improve the maintainability of the docs workflow. The suggestions above are all low-priority enhancements.

Before merging, I recommend:

1. Running the workflow manually on this branch to verify it works
2. Checking the generated documentation output
3. Updating the PR description with test results

---

[macroscopeapp]

Generate iOS reference docs with Swift-DocC in GitHub Actions deploy workflow to get the reference docs generating

Switch the docs CI from Jazzy to Swift-DocC, run on macos-latest, build with swift build, and publish DocC output to ./docs with hosting base path xmtp-ios. Remove the update-package job and restrict the workflow trigger to main and docs. Add .gitignore rules for generated docs and delete Ruby gem files.

📍Where to Start

Start with the deploy job in .github/workflows/docs.yml, focusing on the swift package generate-documentation step and artifact upload path.

---

Macroscope summarized 84cd12f.

[macroscopeapp]

I recommend approving @jhaaaa’s PR (analysis below). Auto-approval is disabled due to the CODEOWNERS requirement.

Reasoning

Eligibility
This PR only updates the documentation generation workflow, switching from Jazzy to Swift's native DocC. It removes related Ruby dependencies and updates .gitignore. These changes have no runtime impact on the application code.

Ownership
@jhaaaa isn't a code owner for 4 files:

• Gemfile
• Gemfile.lock
• .gitignore
• .github/workflows/docs.yml

[jhaaaa]

Moving to libxmtp.