Cargo doc instead of mdbook?

Hi! I typically use mdbook for all our documentation, but I often feel the distance from actual code when writing technical/developer/design type documentation. In both cases I'm using markdown to write prose, code listings and mermaidjs.

<snark>OTOH, writing prose in code is about as painful as writing HTML in code ooooh!</snark>

However, cargo doc allows markdown files to be included, and so I wonder whether this is the answer I'm looking for: continuing writing in markdown, but assembling it using cargo doc.

Has anybody tried this, and do you have any experience points to share?

P.S. I used emacs for a bunch of years and feel in love with org mode, so cargo doc, particularly cargo (doc) tests is very appealing!

I think it works fine for developer facing documents, some projects already do this, for example, the documents for snafu contains sections written in separate markdown files and included in the source code, the rendered documents looks pretty decent I would say.

I've seen crates doing clever things about the automatic link resolution for rust code, for example, clap include separate markdown documents as #[doc] attributes (and also include actual rust file as example code), and they use re-exports as navigation links, you'll find constructs like the following snippets in their source code:

2 Likes

Just fyi, you can do

cargo doc -Zunstable-options -Zrustdoc-scrape-examples

To include examples from the examples folder in your api documentation. It's great.

See the rustdoc docs for more info. There are crates that do this, but I couldn't find the original post where I found these examples.

EDIT

Found it

Post

Example

3 Likes

(thanks @nerditation and @SebastianJL)

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.