How to create link between rustdoc and mdbook?

#1

In case this is a A/B problem, what I'm trying to do is to have both a API centrist documentation (with rustdoc), and a global overview (with mdbook).

All the documentation (rustdoc + mdbook) is going to be build locally. I can use relative path to locate the root of the crate or the root of the mdbook (it will be in a documentation subdirectory of my crate).

I would like to add links to and from rustdoc and mdbook. Is it somehow possible? Ideally I would like to be able to use struct.MyType.html into the mdbook, and have the url pointing to the relevant rustdoc section.

2 Likes
#2

When I saw that @alice liked my post but didn't answered it, I knew I was doomed!

In case someone is interested, I opened an issue on the issue tracker of mdbook.

2 Likes
#3

I'm sorry I can't help with this one :sweat_smile:

2 Likes
#4

You can have a look at how ::safer_ffi hacks its way into it, using a build_docs.sh script to generate the docs into a folder that is then moved inside a directory within the mdbook-generated static site.

  • There is an optional parameter you can feed it to override the "root path" (since github.io sites may prefix paths with the name of your repo). When missing it defaults to /, useful for local testing.

  • Something I did not knew at the time I wrote the scripts (because hardly documented) about mdbook which would have simplified my script, is that a directory located in the src/ directory of the mdbook is copied to the generated dir for the static site. So, if you copy/move target/doc into your_mdbook_path/src/, mdbook serve will Just Work™, with the paths for your rustdoc-generated docs starting at /doc/your_crate_name/index.html (or {ROOT_PATH}doc/... if using the template trick).

2 Likes