Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Include images in rustdoc output #32104

Open
emoon opened this issue Mar 7, 2016 · 20 comments
Open

Include images in rustdoc output #32104

emoon opened this issue Mar 7, 2016 · 20 comments

Comments

@emoon
Copy link
Contributor

@emoon emoon commented Mar 7, 2016

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
Copy link
Member

@bluss bluss commented Mar 7, 2016

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

@jimblandy
Copy link
Contributor

@jimblandy jimblandy commented Apr 26, 2018

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

cc: @steveklabnik

@steveklabnik
Copy link
Member

@steveklabnik steveklabnik commented Apr 26, 2018

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
Copy link

@TotalKrill TotalKrill commented Jul 30, 2018

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

@ZhangHanDong
Copy link

@ZhangHanDong ZhangHanDong commented Nov 21, 2018

It‘s work

//! <div>
//! <img src="../../../images/rustbook.jpg" height="300" width="220" />
//! </div>
//! <hr/>
@crepererum
Copy link
Contributor

@crepererum crepererum commented Nov 22, 2018

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
Copy link

@ZhangHanDong ZhangHanDong commented Dec 1, 2018

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

@crepererum
Copy link
Contributor

@crepererum crepererum commented Dec 1, 2018

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
Copy link

@TotalKrill TotalKrill commented Dec 22, 2018

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
Copy link

@donbright donbright commented Apr 15, 2019

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.

@GuillaumeGomez
Copy link
Member

@GuillaumeGomez GuillaumeGomez commented Jan 31, 2020

I don't think this is a good idea: it'd force rustdoc to download the content to know if it's an image or a video or anything else. Also, from a security perspective, I think this wouldd be an issue as well (cc @pietroalbini ).

@pietroalbini
Copy link
Member

@pietroalbini pietroalbini commented Jan 31, 2020

From my point of view it'd be fine if rustdoc included images present in the crate's source tarball into the generated docs. It definitely should not download images from the Internet.

@GuillaumeGomez
Copy link
Member

@GuillaumeGomez GuillaumeGomez commented Jan 31, 2020

I don't see the difference between local image and one from the internet. In both case, it can't be trusted.

@TotalKrill
Copy link

@TotalKrill TotalKrill commented Jan 31, 2020

Well then, I am guessing the current way to input it into a comment as base64 isnt much different.

The end result should still be an image shown online, wherever it is a link to an image, or an image generated from base64.

Nothing can be trusted anywhere, but still we do it.

@pietroalbini
Copy link
Member

@pietroalbini pietroalbini commented Jan 31, 2020

I don't see the difference between local image and one from the internet. In both case, it can't be trusted.

You can do the same thing with workarounds today, and you'll still be able to do it with workarounds in the future. Besides, it's a legit feature request.

@GuillaumeGomez
Copy link
Member

@GuillaumeGomez GuillaumeGomez commented Jan 31, 2020

Indeed, I don't know why but I was kinda confusing the URL thing... Then yes, it'll require to move the file content to a given target and be sure to not have conflicts. Urg... Headache ahead! I'll try to do it in not too long from now.

@GuillaumeGomez GuillaumeGomez self-assigned this Jan 31, 2020
@Luthaf
Copy link

@Luthaf Luthaf commented Jan 31, 2020

Then yes, it'll require to move the file content to a given target and be sure to not have conflicts.

A possible solution for this would be to hash the image content, move them to target/doc/{crate}/static-img/{hash}.{ext}, and rewrite the links in the generated HTML accordingly. (static-img not being a valid module name should not clash with other files)

@GuillaumeGomez
Copy link
Member

@GuillaumeGomez GuillaumeGomez commented Feb 1, 2020

If I hash the path, it might be easier, indeed. I didn't want to create another folder but that would fix the naming conflict so I think I'll do that. Thanks for the tips!

@Luthaf
Copy link

@Luthaf Luthaf commented Feb 1, 2020

I would rather hash the file content than the path, since the same file might be referred to by different .rs files, using different paths.

@tspiteri
Copy link
Contributor

@tspiteri tspiteri commented Apr 15, 2020

With this feature, would it also be possible to link to a file included in the crate inside the doc(html_root_url) attribute?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.