Repository navigation
Include images in rustdoc output #32104
Description
Activity
I second this, images can greatly help explaining (geometrical split_at example).
Reacted by cospectrum and Christoph J. ScherrSince the focus is on doxidize now, rustdoc is in maintenance-only mode. Should this be closed?
cc: @steveklabnik
I'd say "maintenance-only" mode is a bit strong;
rustdochas its own team and they're still working on new stuff. It's entirely possible that this will get added to rustdoc.Reacted by bluss, Jim Blandy, don bright, Carlos Melo, Kristijan Sedlak, TornaxO7 and qouteallWould love this as well! Has there been any updates?
It‘s work
//! <div> //! <img src="../../../images/rustbook.jpg" height="300" width="220" /> //! </div> //! <hr/>Reacted by bistack, TornaxO7, Andrew Sonin and ynnThat 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.Reacted by kennytm, Robert, Eric Mink and Johannes Holland@crepererum you're right. One solution is to separate the doc file and manually modify it.
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 )
Reacted by TotalKrill and Tianyi ShiI 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.
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.pngfile, encoding it as base64, and inline it into the html file itself, without the user having to insert base64 directly into their rust comments.Reacted by Danilo Bargen, Tianyi Shi, Kristijan Sedlak, achary, bistack, bever1337 and Christoph J. ScherrReacted by Frederik Holm Strøm27 remaining items
I opened an RFC for this feature: rust-lang/rfcs#3397
Reacted by Andreas Borgen Longva, Yoltic Cruz Tello, Danilo Bargen, Frédéric Tobias Christ, Erik Hennig, Dilawar Singh and qouteall- added a commit that references this issue
on Jul 31, 2023 - added a commit that references this issue
on Aug 10, 2023 This is how I did it in Github Actions, not complicated, might not be worth a full RFC. However, it would be nice if rustdoc could do this natively so it could check if the image link is valid. ryanpeach/OrbitingSandRust#102
Sure, it works in your CI, but how does it work for crates depending on yours? Are your images included into your crate package? If so you're doing something very wrong.
Just including my PR so that others looking for a more immediate solution who find this on google can see an example.
Sure, it works in your CI, but how does it work for crates depending on yours? Are your images included into your crate package? If so you're doing something very wrong.
Is there a particular issue with including images in a crate package besides size?
Not that I can think of. The RFC is currently on hold until the potential cargo archive format becomes a reality (as mentioned here).
If so you're doing something very wrong.
@GuillaumeGomez So if this is the only way to do it, then why is it "very wrong"?
I answered (too aggressively) to:
This is how I did it in Github Actions, not complicated, might not be worth a full RFC. However, it would be nice if rustdoc could do this natively so it could check if the image link is valid. ryanpeach/OrbitingSandRust#102
In particular this part:
might not be worth a full RFC
The fact that we might includes megabytes (if not more) of data by default only for documentation sounds like something that should be very carefully considered.
- added a commit that references this issue
on Jul 7, 2024 I'd like to second this feature request too.
In Masonry, as a GUI library, we want to include a lot of images in our docs (we even generate and check the images from our unit tests, so the images are guaranteed to stay up to date). We had a long discussion (#masonry > Screenshots in doc) where we considered a lot of alternatives, and all of them were pretty fragile.
We ultimately decided not to include all images in our data pack (we were worried about the tarball size increase, though in retrospect maybe we shouldn't have).
Overall, including screenshots stored in the repository tree is currently kind of a pain, unless you're willing to include them in the crate tarball unconditionally.
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
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.