mdbook-include-rs

A preprocessor for mdBook that lets you include code from external Rust source files with extraction capabilities. This makes it easy to maintain code examples that are always in sync with your actual codebase.

Features

• Include entire source files or just the parts you need (specific functions, methods, structs, etc.)
• Automatically include dependencies for functions when needed
• Show only function bodies when desired, with supporting types shown separately
• Extract methods from structs and trait implementations cleanly
• Your code examples stay as regular source files that you can compile and test

Installation

First, install the preprocessor:

cargo install mdbook-include-rs

Then, modify your book.toml file:

[book]
title = "My Book"
authors = ["Your Name"]

# Add the preprocessor to your mdBook
[preprocessor.include-rs]

# Optional: Specify a base directory for all file paths
# If not provided, paths will be relative to each markdown file's directory
# [preprocessor.include-rs]
# base-dir = "examples"

Usage Examples

Include a Complete Source File

To include an entire source file:

```rust
#![source_file!("source_file.rs")]
```

This will include the entire contents of the file, with use statements automatically filtered out for cleaner output.

Include Just a Function Body

To include just the body of a specific function (without the function declaration):

```rust
#![function_body!("source_file.rs", hello_world)]
```

The output will only contain the content inside the function body, not the function declaration itself.

Include a Function with Dependencies

If your function depends on other types or functions, you can include them too:

```rust
#![function_body!("src/models.rs", User::display_profile, [struct User, trait Displayable, impl Displayable for User])]
```

This will include:

1. The User struct definition
2. The Displayable trait definition
3. The implementation of Displayable for User
4. And finally, the body of the display_profile method

The dependencies will be included in the order you list them, with the main function's body appearing last.

Dependency Types

You can include various types of dependencies:

• struct StructName - includes a struct definition
• trait TraitName - includes a trait definition
• impl StructName - includes all methods in an impl block for a struct
• impl StructName::method_name - includes a specific method from an impl block
• impl TraitName for StructName - includes a trait implementation
• function_name - includes another function

Real-World Example

For a document explaining user authentication:

# User Authentication

Our system handles authentication with a simple API:

```rust
{{#function_body!("src/auth.rs", authenticate_user, [struct Credentials, struct User, fn validate_password])}}
```

Behind the scenes, password hashing works like this:

```rust
{{#function_body!("src/auth.rs", hash_password)}}
```

How It Works

The preprocessor:

1. Parses your markdown looking for code blocks with include-doc directives
2. Uses Rust's syn library to parse and extract the requested code elements
3. Formats the extracted code with proper syntax highlighting
4. Replaces the directive in your markdown with the extracted code

Command Line Interface

As per the mdBook preprocessor standard:

# Check if the preprocessor supports a renderer
mdbook-include-doc supports <renderer>

# Process a book
mdbook-include-doc pre-process <path-to-book>

License

This project is licensed under:

• Apache License, Version 2.0