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 · 9 comments

Comments

Projects
None yet
9 participants
@emoon
Copy link
Contributor

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

This comment has been minimized.

Copy link
Contributor

bluss commented Mar 7, 2016

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

@jimblandy

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link
Member

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

This comment has been minimized.

Copy link

TotalKrill commented Jul 30, 2018

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

@ZhangHanDong

This comment has been minimized.

Copy link

ZhangHanDong commented Nov 21, 2018

It‘s work

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

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link

ZhangHanDong commented Dec 1, 2018

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

@crepererum

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment