profile
viewpoint

Ask questionsInclude images in rustdoc output

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.

rust-lang/rust

Answer questions 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.

useful!

Related questions

Spurious NaNs produced by trig functions with valid inputs on Windows GNU toolchains hot 2
using 'cargo install xsv' on windows 10 triggers rustc internal error hot 1
chain() make collect very slow hot 1
if/while Some(n) = &mut foo sugar will leak a temporary mutable borrow to current scope in particular situation hot 1
build an empty project failed (undefined reference to `__onexitbegin') hot 1
Invalid collision with TryFrom implementation? hot 1
Crater runs for Rust 1.38.0 hot 1
Spurious NaNs produced by trig functions with valid inputs on Windows GNU toolchains hot 1
under latest MinGW, cannot link with C code using stdout hot 1
Archive all nightlies hot 1
Building LLVM with Clang fails hot 1
Internal compiler error: can't buffer lints after HIR lowering hot 1
E0373 help suggests `move async` but the correct syntax is `async move` hot 1
Tracking issue for `Option::contains` and `Result::contains` hot 1
async fn + rustfmt don't "just work" inside of RLS hot 1
Github User Rank List