How to Generate Documentation for OpenLogi: A Complete Guide

Run RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --document-private-items while excluding the GUI crates (openlogi-ui, openlogi-desktop, openlogi-overlay, and openlogi-agent) to generate the OpenLogi API documentation locally.

OpenLogi uses Rust’s native documentation toolchain, cargo doc, to produce comprehensive HTML documentation for its workspace crates. Because the project includes graphics-intensive GUI components that rely on platform-specific toolchains, the documentation workflow deliberately excludes those crates to ensure fast, cross-platform builds. Following the steps in docs/DEVELOPMENT.md allows you to generate documentation for the core library components without requiring macOS development tools.

Why GUI Crates Are Excluded from Documentation

The OpenLogi repository contains several GUI-related crates—openlogi-ui, openlogi-desktop, openlogi-overlay, and openlogi-agent—that depend on the GPUI framework and platform-specific graphics APIs. According to the source code analysis, including these crates would require:

• A full macOS toolchain with Xcode 16+ and Metal support
• Complex shader compilation steps
• Significantly longer build times

Since most API consumers only need documentation for the core, HID, and non-GUI agent crates, the project excludes these components by default. This exclusion is hardcoded in the development scripts and the GitHub Actions workflow (.github/workflows/ci.yml) to ensure documentation generation remains fast and platform-agnostic.

Prerequisites

Before generating documentation, ensure you have the Rust toolchain installed. OpenLogi requires the stable Rust toolchain, which you can install via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Verify your installation with cargo --version. The documentation generation process relies on standard Rust tooling with no additional dependencies required for non-GUI crates.

Generating Documentation Locally

You can generate documentation using either the standard cargo doc command with specific flags or the project's xtask helper.

Using cargo doc Directly

The canonical command for generating OpenLogi documentation excludes the GUI crates and treats documentation warnings as errors. Run this from the repository root:

RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --document-private-items \
  --exclude openlogi-ui \
  --exclude openlogi-desktop \
  --exclude openlogi-overlay \
  --exclude openlogi-agent

This command:

• Sets RUSTDOCFLAGS="-D warnings" to fail on broken intra-doc links or missing documentation
• Uses --no-deps to skip documenting dependency crates
• Includes --document-private-items to generate docs for internal APIs
• Excludes the four GUI crates that require platform-specific graphics toolchains

After running, open target/doc/openlogi/index.html in your browser to view the generated documentation.

Using the xtask Helper (Optional)

OpenLogi provides an xtask wrapper in xtask/src/main.rs that automates the exact CI documentation command. This approach ensures consistency between local builds and CI verification:

cargo run -p xtask -- ci doc

The xtask implementation invokes the same cargo doc command used in the CI pipeline, including the GUI crate exclusions and strict warning flags defined in the workspace Cargo.toml.

Understanding the CI Documentation Pipeline

The GitHub Actions workflow defined in .github/workflows/ci.yml includes a dedicated "rustdoc (non-GUI crates)" job that runs on every push. This job executes the same cargo doc command described above, ensuring that:

• Documentation warnings are caught before merging
• The generated docs remain up-to-date with the codebase
• Platform-specific GUI dependencies do not block CI runs on Linux or Windows

The CI configuration references the workspace structure defined in Cargo.toml and follows the standards documented in docs/DEVELOPMENT.md.

Summary

• OpenLogi documentation is generated using cargo doc with strict warning flags to ensure quality
• GUI crates are excluded (openlogi-ui, openlogi-desktop, openlogi-overlay, openlogi-agent) because they depend on macOS-specific Metal and GPUI toolchains
• Use RUSTDOCFLAGS="-D warnings" to treat documentation warnings as fatal errors during generation
• The xtask helper (cargo run -p xtask -- ci doc) provides a convenient wrapper that matches the CI pipeline exactly
• Documentation is output to target/doc/ and can be browsed locally at target/doc/openlogi/index.html

Frequently Asked Questions

Why does OpenLogi exclude GUI crates from documentation generation?

The GUI crates depend on the GPUI framework and require macOS-specific graphics toolchains including Xcode 16+ and Metal for shader compilation. Including them would dramatically increase build times and break documentation generation on Linux and Windows systems. The project focuses documentation on the core library components that are platform-agnostic.

What does the RUSTDOCFLAGS="-D warnings" flag do?

This environment variable instructs Rustdoc to treat all documentation warnings as fatal errors. According to the OpenLogi CI configuration in .github/workflows/ci.yml, this ensures broken intra-doc links, missing documentation strings, or formatting issues surface immediately during development rather than going unnoticed.

Can I generate documentation for the GUI crates on macOS?

While technically possible if you have the full macOS development toolchain (Xcode 16+, Metal SDK), the project does not officially support this in the default workflow. The Cargo.toml workspace configuration and CI scripts specifically exclude these crates to maintain cross-platform compatibility and fast build times for the majority of contributors.

How do I view the generated documentation locally?

After running cargo doc, the HTML files are generated in the target/doc/ directory. You can open the main entry point by running open target/doc/openlogi/index.html on macOS, or by navigating to that path in your file browser and opening index.html in any modern web browser.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}