(hex)docs: images in documentation comments

[george-grec]

When I document my gleam project, I want to be able to add and reference images, videos or gifs to better explain what the code does in a more visual way. This could be flow charts, images of lustre components or example videos. As the documentation comments support markdown which supports embeds / linking images, I think that would be a good starting point.

I have made a PR with a naive implementation that copies all non-gleam files in the src/ directory into the build output of the docs so they can be referenced in doc comments. Louis rightfully mentioned that we don't want to add unused files to hexdocs and should agree on an approach before implementing this.

These are the options I can think of right now:

1. Keep using the src/ directory but only add files to the build output that are actually referenced in doc comments.
2. Do not use the src/ directory and define a directory, let's say docs/, at the root of the project where we expect all documentation assets to be.

Questions for option 2:

• Do we make the directory location configurable, for people who don't want to use docs/?
• If so, do we require such a docs directory to be defined explicitly or do we always use a default directory (like docs/) unless the user configures something else?
• Do we still need to check if a file is referenced in a doc comment before we add it to the output or can we assume that all files should be added?
• If we make the docs directory configurable, we probably want to make it possible to change the location without the user having to change all references in all comments. Do we do something like this?

/// See ![example]($docs_dir/path/to/image.png)
pub fn wibble() {
}

Questions for both options:

• Do we want to add special support for .md files? This may be out of scope, but if we already have a place in the project for doc assets, we might do the same thing as the pages config option in the gleam.toml but without the user having to add every file manually.
• Do we want to add support for referencing the docs directory in .md files (e.g. README.md)? That would also be useful imo.

Side note: I'm not sure which option I prefer. Option 1 would be nice because it's very obvious where the file you reference is and keeping documentation close to your code makes it easier and more likely that you keep it up-to-date, but it might clutter the src/ directory. If we choose something like option 2, I would prefer if we don't make the directory configurable and settle on a default directory.

[lpil]

Do we need to specify a particular directory? I would think that anywhere within the project root should be fine. We'd need to parse the docs and follow the image paths regardless, so there's no particular need to have a specific directory to traverse.

Do we want to add support for referencing the docs directory in .md files (e.g. README.md)? That would also be useful imo.

What would that do?

[george-grec]

@lpil

Do we need to specify a particular directory?

The motivation for that is my assumption that most projects will have one folder where people put most of their assets and it would be nicer to reference them the same way everywhere.

Here is an example project where we could introduce pain points if we do not consider this carefully:

├── README.md
├── docs
│   └── images
│       └── example.png
├── gleam.toml
├── manifest.toml
├── src
│   ├── glexample.gleam
│   └── wibble
│       └── wobble
│           └── wabble
│               └── wubble
│                   └── webble
│                       └── foo.gleam
└── test
    └── glexample_test.gleam

If I add a comment in foo.gleam, how should I reference example.png?
I want to avoid this:

/// See ![example](../../../../../../docs/images/example.png)
pub fn foo() {
  todo
}

One option is to always start at the root directory

/// See ![example](docs/images/example.png)
pub fn foo() {
  todo
}

But in some projects this might also be very deep in some sub-sub-subfolder that's used for many more things.
An extreme example would be resources/project/assets/latest/guides/docs/images/, then it would look like this:

/// See ![example](resources/project/assets/latest/guides/docs/images/example.png)
pub fn foo() {
  todo
}

That's where the option comes in to make a configurable docs folder that can be referenced by something like $docs_dir/images/example.png. But we don't have to optimize for everything, I'm fine if we just accept this edge case.

---

Do we want to add support for referencing the docs directory in .md files (e.g. README.md)? That would also be useful imo.

What would that do?

The README.md is used as the index page of the project on hexdocs. I'm sure it would be useful to be able to embed local images just as in doc comments.

Something like

// In README.md

# glexample

Glexample is the best gleam example project available.
This is an example image ![example](/path/to/example.png)

[lpil]

I see! Parsing the README too sounds good. Perhaps we skip embedded HTML for now?

Keen to hear what other people think RE paths.