Include images in rustdoc output

[emoon]

As written by Luthaf over here

https://users.rust-lang.org/t/include-images-in-rustdoc-output/3487

"Hi rustaceans!

Images in documentation can be really useful to provide some insight on algorithms or modules organisation.

It is already possible to insert a link to an image in documentation comment

/// ![Alt version](url://for/this/image.png)

But using this method, we only get to include images already available in some place of Internet.

Is it a way to make rustdoc copy some files to the target/doc folder, so that it is easy to include specific images in the documentation? The same could go for other static files, like specific CSS or JS.

Is it possible yet? If not, do you think it is worth it?"

I this this would be awesome to include as sometimes using images is much easier when explain something than showing text.

[bluss]

I second this, images can greatly help explaining (geometrical split_at example).

[jimblandy]

Since the focus is on doxidize now, rustdoc is in maintenance-only mode. Should this be closed?

cc: @steveklabnik

[steveklabnik]

I'd say "maintenance-only" mode is a bit strong; rustdoc has its own team and they're still working on new stuff. It's entirely possible that this will get added to rustdoc.

[TotalKrill]

Would love this as well! Has there been any updates?

[ZhangHanDong]

It‘s work

//! <div>
//! <img src="../../../images/rustbook.jpg" height="300" width="220" />
//! </div>
//! <hr/>

[crepererum]

That only works locally if you're building the docs for your own crate. Does not work on docs.rs or if the crate is a dependency of something else.

Background:
The referred image is not copied / tracked.

[ZhangHanDong]

@crepererum you're right. One solution is to separate the doc file and manually modify it.

[crepererum]

Or you host the image somewhere, like on GitHub pages (that's what ndarray is doing here https://github.com/rust-ndarray/ndarray/blob/master/src/impl_views.rs )

[TotalKrill]

I think what would be most optimal is if there could be a folder where images for the doc could be stored in the crate folder structure.

There is one huge painpoint here though, and that is a lot of people just love to generate extremely large pictures to include in the crates. For no reason: ClickBait article with example

So if this should be in the code, the file size should be limited.

[donbright]

There is a workaround.

You can insert the image data, base64 encoded, directly into your rust source code comments,
and rust-doc will pass this to the html, where it will become an inline image in the html code.
This is based on rfc2397 aka the data URI.

http://www.bigfastblog.com/embed-base64-encoded-images-inline-in-html
https://tools.ietf.org/html/rfc2397

$ base64 ../images/mypicture.png  | awk ' { print "/// " $1 } ' > myfile.b64

myfile.rs:

/// my function does blah blah blah. here is a picture:
/// <div>
/// <img src="data:image/png;base64,
/// iVBORw0KGgetcetcetc                       <-- copy/paste myfile.b64 here
/// ....                                      <-- several dozen lines of myfile.b64
/// JDIOIDondio00778==                        <-- last line of myfile.b64
/// ">
/// </div>
fn myfunction(x:u64)->bool { x<5 }

$ cargo doc

Now the html file under target/whatever will have the png image baked inside of it as base64 code.

I think this might be possible with svg but havent tested.

---

I think it might be nice to consider if rustdoc could do this on it's own, automatically, taking a <img src=../../image.png file, encoding it as base64, and inline it into the html file itself, without the user having to insert base64 directly into their rust comments.