# rustdoc-markdown
This crate extracts documentation from crates.io packages and renders it into
a monolithic markdown document.
The initial use case was for generating documentation context for large language
models.
In some places the markdown is not technically valid since some headers nest
higher than the h6 level, but it's assumed an LLM would benefit more from the
consistent structure.
As a trade-off that reduces the size of the output, but makes the documentation
of types more indirect, there is support for rolling up "Common Traits" for the
crate and for each module so that the list of implemented traits, per-type,
can be more concise. This feature can be disabled.
If a package contains a `README.md` and examples in an `examples/` directory,
these are also folded into the documentation.
## Command Line
Install:
```bash
cargo install rustdoc-markdown
```
Generate Markdown for `rustdoc-types` version `0.39.0`:
```bash
rustdoc-markdown print rustdoc-types 0.39.0 --output rustdoc-types-api.md
```
Generate Markdown for a local crate:
```bash
rustdoc-markdown print my-local-crate --manifest path/to/my-local-crate/Cargo.toml --output my-local-crate-api.md
```
## Library Usage
`rustdoc-markdown` can also be used as a library to integrate documentation generation
into other tools.
See the [library documentation](https://docs.rs/rustdoc-markdown) for `rustdoc_markdown::Printer`
for an example of how to:
1. Find a crate on crates.io.
2. Download and unpack it.
3. Run `rustdoc` to get the `rustdoc_types::Crate` data.
4. Read extra information like README and examples.
5. Use the `Printer` to generate the Markdown documentation.
# Cargo limitations
One awkward paper cut with the `rustdoc-markdown` CLI is that the `--build-dir`
option cannot point within a Cargo project/ workspace, due to the way it needs
to unpack and inspect packages from crates.io.
The problem is that Cargo will unconditionally walk up the filesystem looking
for `Cargo.toml` files to find the workspace root and it will get confused while
trying to inspect a package if it then finds an un-related `Cargo.toml` above
it.
By default the `--build-dir` will be set to a temporary directory like
`/tmp/rust-markdown-<crate_name>` to avoid this problem.
Ideally though Cargo should have some mechanism for limiting how far up the
filesystem it searches for workspaces so that it's possible to sandbox it's
behavior.
Ref:
- <https://github.com/rust-lang/cargo/issues/7871>
- <https://github.com/rust-lang/cargo/pull/15620>
## Dependencies
It depends on:
- `nightly-2025-11-22` Rust toolchain.
- `rustdoc-types` version `0.57`.
See the changelog for `rustdoc-types` for compatibility information when updating the toolchain:
<https://github.com/rust-lang/rustdoc-types/blob/trunk/CHANGELOG.md>
## Versioning
This project aims to have it's minor version track the minor version of the most
recent stable Rust release that's aligned with the nightly toolchain it depends
on.
## License
Licensed under either of
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
https://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or
https://opensource.org/license/mit)
at your option.