I kept getting annoyed switching between my terminal and browser just to look up API docs. As someone who spends most of their time in the terminal it completely breaks my flow. Plus I forget things constantly so I'm always going through the docs.

So I tried making this for myself. I mean it's obviously a very simple idea and I am sure many people have been thinking about making something like this, especially those who use obsidian and likes taking notes. This is already possible with rustdoc-md, but it unfortunately makes a single markdown file and it also doesn't add reference links to types (like you can click and go to in docs.rs or local html docs). This takes rustdoc's JSON output and generates markdown files you can grep through, read in your editor, or just browse locally. One file per module with cross-reference links between types and modules (this has been harder to work out than I thought it would be)

Installation and use is pretty simple, but rustdoc JSON is still nightly so you will need the nightly toolchain installed. Includes private private items by default, if you want the public API only, add the --exclude-private flag.

cargo install cargo-docs-md 
cargo docs-md docs

If you want all optional/feature gated dependencies documented too, just pass:
cargo docs-md docs -- --all-features

That's it. It builds the JSON and generates markdown for your crate and all dependencies. You get a generated_docs/ folder with everything.

It's not perfect and obviously needs a lot more work. There are edge cases with re-exports and some formatting quirks. But it's been good enough for my workflow.

repo: GitHub - consistent-milk12/docs-md: A CLI tool that converts Rust's rustdoc JSON output into readable, per-module markdown files.
crates.io: crates.io: Rust Package Registry

Usually I don't really share my work, but I figured others might find it useful, or even come up with better ideas and solutions for the current limitations. An interesting thing that may be of more help is that you get navigable markdown docs in github that you can just add in your repo directly, with types having reference links to other modules, specific location on the current file, or even cross-crate (not all of them work, as there are many edge cases to handle)

I am currently working on redesigning the whole thing to include source code for all of the dependencies directly using syn and rustdoc json together, as I just end up copying the source code of the dependencies to my project anyway to go through :'D. And diverging from the structure rustdoc uses to something more that will be more helpful for the markdown format. The initial ideas for it is in a separate branch of the repo. I am not sure whether it will be a feasible thing to publish to publicly though? I don't really have much idea about how licenses will work in this case.

EDIT: You can check out how the markdowns with type links work in the repo, I have added the whole generated_docs/ for this project in it.

1 post - 1 participant

Read full topic