Gleam: Link from hex docs back to repository

[michaeljones]

It would be great to have a link in the published docs for a package back to the repository to make it easier to explore and jump around between the code and the docs. I would start with just one link in the header or sidebar navigation but I guess this could also be extended to linking from types & functions back to the source code definitions.

It could work like the Rust docs:

Which I guess is driven by the repository field in the Cargo.toml file. We might consider having a similar field in the gleam.toml file.

I imagine the source code linking would be more complex and might involve tying the current build of the docs to a particular git tag or similar commit reference in the repository. A first pass might only work for Github (and other major hosting sites) where the URL format for referencing a line in a file on a tag is known.

Elixir docs provide a </> link next to each function which links to the source code:

https://hexdocs.pm/phoenix_html/Phoenix.HTML.Form.html#label/1

[lpil]

Good idea! Let's do this.

[michaeljones]

Great! How would you like it to look?

Nav bar option might be something like:

Could also go towards the top. Depending on how far down we're happy with it being for large projects with lots in the side bar.

Top bar option might be something like this:

Though pink on pink is not readable and black on pink might be too prominent up there.

Or we could try something more like a drop down menu like the Rust does.

As you can tell, I'm no designer. Happy for suggestions and obviously for it to evolve once the basic functionality is there.

[CrowdHailer]

What about white on pink at the top? The pink seems to be saturated enough that that could work?

[lpil]

Now I think about it we do already have a links section! Though it seems the HTML is currently incorrect

https://github.com/gleam-lang/gleam/blob/f4cda97edf004e827f53376249622fc7fd966049/templates/documentation_layout.html#L46-L53

And the links value is hard coded to an empty slice.

https://github.com/gleam-lang/gleam/blob/fe537d095c10b4b2c6b91e9538f7b139c85110a7/src/docs.rs#L59

We will need to add links to the docs config struct:

https://github.com/gleam-lang/gleam/blob/fe537d095c10b4b2c6b91e9538f7b139c85110a7/src/config.rs#L36-L39

And then make use of this in the docs generation.

We could also have gleam new generate a gleam.toml with a commented out link section with some hints on how to add links

name = "my_lib

# [docs]
# links = [
#   { title = 'GitHub', href = 'https://github.com/username/project_name'}
# ]

[michallepicki]

This discussion reminded me of an idea of hexpm exposing their "Links" section from a project page for use by hexdocs documentation. An advantage of such approach is that whenever a project changes its website address or source hosting, it would be automatically reflected in the documentation for old package versions. Related issue with some more background: https://github.com/gleam-lang/gleam/issues/844

[michaeljones]

I've updated the PR to use the approach suggested by @lpil above. Not a big change so happy to rework it further if alternatives seem better.