# How to Generate Documentation for OpenLogi: A Complete Guide

> Generate OpenLogi API documentation locally with a simple Cargo command. This guide provides the exact steps to build your project docs efficiently.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: how-to-guide
- Published: 2026-08-22

---

**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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/.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:

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

```bash
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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/main.rs) that automates the exact CI documentation command. This approach ensures consistency between local builds and CI verification:

```bash
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`](https://github.com/AprilNEA/OpenLogi/blob/main/Cargo.toml).

## Understanding the CI Documentation Pipeline

The GitHub Actions workflow defined in [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.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`](https://github.com/AprilNEA/OpenLogi/blob/main/Cargo.toml) and follows the standards documented in [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/.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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/index.html) in any modern web browser.