Crate rustdoc_markdown 

rustdoc-markdown is a tool to convert Rust crate documentation into a monolithic Markdown document, primarily designed for consumption by Large Language Models (LLMs).

It achieves this by:

1. Fetching crate information from crates.io (if not using a local manifest).
2. Downloading and unpacking the crate source.
3. Running rustdoc to generate JSON output (rustdoc_types::Crate).
4. Parsing the Cargo.toml of the crate.
5. Optionally reading extra information like the crate’s README.md and source code examples from the examples/ directory.
6. Processing the rustdoc_types::Crate and supplementary information.
7. Rendering a structured Markdown document.

Key Features

• LLM-Optimized Output: The Markdown is structured for clarity and conciseness, aiming to provide effective context for LLMs. Header levels might exceed standard Markdown (h6) to maintain a consistent hierarchical structure.
• Comprehensive Documentation: Includes API documentation, README, and examples.
• “Common Traits” Summarization: To reduce output size, frequently implemented traits can be summarized at the crate and module levels. This can be disabled.
• Path Filtering: Allows generation of documentation for specific modules or items.
• Template Mode: Can output template markers instead of actual documentation, useful for identifying missing docstrings.

Main Entry Points

• Printer: The core struct responsible for orchestrating the documentation generation process. It uses a builder pattern for configuration.
• run_rustdoc: A utility function to execute rustdoc and parse its JSON output.
• CrateExtraReader: Reads supplementary information like READMEs and examples.

Example Usage (Library)

use anyhow::Result;
use cargo_manifest::Manifest;
use rustdoc_markdown::{Printer, CrateExtraReader, run_rustdoc, cratesio};
use std::path::Path;
use reqwest::Client; // Add this line

async fn generate_docs_for_crate(
    crate_name: &str,
    version_req: &str,
    output_md_path: &Path,
    build_dir: &Path,
) -> Result<()> {
    // 1. Setup client and directories
    let client = Client::new();
    std::fs::create_dir_all(build_dir)?;

    // 2. Find the best version on crates.io
    let target_version = cratesio::find_best_version(
        &client,
        crate_name,
        version_req,
        false, // include_prerelease
    )
    .await?;

    // 3. Download and unpack the crate
    let crate_dir = cratesio::download_and_unpack_crate(
        &client,
        &target_version,
        build_dir,
    )
    .await?;

    // 4. Parse the crate's Cargo.toml
    let manifest_path = crate_dir.join("Cargo.toml");
    let manifest = Manifest::from_path(&manifest_path)?;

    // 5. Run rustdoc to get rustdoc_types::Crate
    let krate_data = run_rustdoc(
        &crate_dir,
        &target_version.crate_name,
        None,    // features
        false,   // no_default_features
        None,    // target
        true,    // allow_rustup (ensure nightly is available)
    )?;

    // 6. Read extra crate information (README, examples)
    let extra_reader = CrateExtraReader::new(); // Default: reads README and examples
    let crate_extra = extra_reader.read(&manifest, &crate_dir)?;

    // 7. Configure and run the Printer
    let printer = Printer::new(&manifest, &krate_data)
        .crate_extra(crate_extra)
        // .paths(&["::my_module".to_string()]) // Optional: filter by path
        // .no_common_traits() // Optional: disable common traits summary
        ;

    let markdown_content = printer.print()?;

    // 8. Write to output file
    std::fs::write(output_md_path, markdown_content)?;

    println!("Successfully generated Markdown for {} v{} at {}",
             crate_name, target_version.num, output_md_path.display());

    Ok(())
}

Modules

cratesio

Structs

CrateExtra

Holds extra crate information like README and examples.

CrateExtraReader

Builder for reading CrateExtra data from a crate’s source directory.

Printer

Printer is responsible for generating Markdown documentation from a rustdoc_types::Crate.

Constants

NIGHTLY_RUST_VERSION

The specific nightly Rust toolchain version required by this crate.

Functions

run_rustdoc

Runs rustdoc for a given crate and parses the resulting JSON output.