auto_doc 📖

A lightweight, compiler-friendly procedural attribute macro for pulling external Markdown files into Rust documentation.

Keep your source code clean while making your docs easier to author and maintain.

Why use `auto_doc`?

Rust already supports #[doc = include_str!("...")], but this can sometimes interfere with IDE hover tooltips in rust-analyzer and is harder to reason about once procedural macros are involved.

auto_doc reads Markdown files during compilation and emits a clean string literal for the final documentation item, giving you:

consistent rendering in cargo doc
working hover docs in supported editors such as VS Code
simpler source code without inline markdown clutter

Installation

Add this crate to your Cargo.toml:

[dependencies]

auto_doc = "0.1.0"

Usage

By default, auto_doc looks for a file named docs/<item_name>.md relative to the workspace root where the item is defined.

Basic example

use auto_doc::auto_doc;

// Loads documentation from "docs/my_function.md"
#[auto_doc]
pub fn my_function() {
    // ...
}

Custom file paths

Specify one or more explicit Markdown file paths:

use auto_doc::auto_doc;

#[auto_doc(path = "architecture/SAFETY.md")]
pub struct SecureVault;

Multiple files

Combine several Markdown files into one documentation block in declaration order:

use auto_doc::auto_doc;

#[auto_doc("docs/intro.md", "docs/api_spec.md")]
pub trait CoreEngine {
    fn run(&self);
}

You can also use repeated paths = attributes for the same effect:

use auto_doc::auto_doc;

#[auto_doc(paths = "docs/A.md", paths = "docs/B.md")]
pub fn complex_operation() {}

Notes

Paths are resolved relative to the crate root.
Use Markdown files to keep long documentation outside of your source code.
auto_doc is designed to preserve IDE documentation support and avoid macro expansion artifacts.

auto_doc 0.1.1