Including standalone documentation with source docs?


#1

I’d like to write tutorials, etc. that aren’t tied to any particular module and link them from the source docs (generated by cargo doc).

The Documentation section of the book mentions writing standalone markdown files, but it’s a bit sparse.

I got this far:

cargo doc
for f in doc/*md; do rustdoc "$f"; done
mv doc/*.html target/doc/my_crate

(assuming the markdown files are stored in doc/ and then linked from the docstrings in the Rust sources)

This does produce the structure I’m after, but the standalone docs look like unstyled HTML. Ideally, they’d look the same as the source code documentation. And it all seems a bit verbose (e.g. rustdoc accepts only a single file, hence the for loop).

The only way I see is to pass --html-in-header, --html-before-content, etc. to rustdoc to get the same look. Or creating a empty modules and write the tutorials in their docstrings.

So, is there a simpler way to make all this work? I was hoping that cargo doc would do all this automatically, but I couldn’t figure out how.


#2

Oh. There’s a Cargo issue for this: https://github.com/rust-lang/cargo/issues/739.