Images (and other assets) in docs

[george-grec]

Hello! Last time when I went through the lustre/ui documentation, I really wished there were some images to make choosing the right component easier. I wanted to contribute some but that is not easily possible because you can only link to externally hosted images.

I made this PR to change that. I should have probably created a Github issue first for a discussion but the change is so small I just went ahead and did it. This is my first ever PR here, let me know if I did something wrong or forgot something.

How it works
Any asset can be put in the src folder and referenced in documentation comments with a relative path.

Example
Let's say you have an image example.png and you put it under src/example.png.

Let's say this is src/wibble.gleam

/// This is how wibble looks like ![example](./example.png).
pub fn wibble() {
  todo
}

After running gleam docs build --open you will see something like this:

---

Of course, you can use HTML to change the image size.

/// This is how wibble looks like <img src="./example.png" width="150"/>
pub fn wibble() {
  todo
}

[lpil]

Hello! Thank you for this, I agree images would be useful to have.

It would be good to have an issue to discuss the design for this before a PR, we don't merge PRs until a design as been decided upon.

I'm not sure that putting extra files in src is the way to go here, and we certainly don't want to add unused files to hexdocs. There could be all manner of other files in there. Perhaps we want to follow relative image links and copy across referenced files.

Do we want to have any restrictions on image formats and image size?

Once we have a design agreed on we'll need tests along with the implementation also.

Thanks!

[george-grec]

@lpil fair enough, I made an issue here #3731 for further discussions :)