Add metadata to docs output

[straight-shoota]

Currently, the API docs generated by crystal doc contain only minimal information about what it actually documents: apart from the homepage with the obvious README, all other pages only show the repository name in the page title - but this is unreliable because the docs generator takes the first github or gitlab remote URL which might point to an unrelated mirror or not be present at all. And such a HTML page title might not always be visible to the reader. Other important information like the API version needs to be inferred from context, e.g. an URL like crystal-lang.org/api/0.23.0/. Such context cannot necessarily be assumed to be available and/or easily accessible to the reader.

I suggest that every docs page should have at least a reference to the name and version of the documented API and link to an authoritative website. Preferably in a spot with high visibility like the left top corner. Additional information like author, license etc. would also be welcome, but does not need to be displayed as prominently.

A great source for this data would be the shard.yml file available in almost all crystal packages. The compiler deps tool already directly integrates the shards binary which is distributed as part of the crystal package. To read metadata from the shard file however would require to include the shard spec parser into the standard library.

It should also be possible to provide the metadata as command line arguments to the docs generator, if there is no shards.yml file or to explicitly overwrite specific values. The stdlib (which does not have a shards.yml file) could be handled as a special case with hardcoded metadata.

[straight-shoota]

I'd like to proceed with this. Here is a more detailed plan on how this can be implemented.

For a minimum, I think the following properties should be available to the docs generator. This meta data can be published as a header and also be used in other places (for example meta tags, page title).

• name: shard name (or equivalent)
• version: release version. If not on a release (e.g. master), we should consider whether it should show the actual commit data or just a label (=master).

Besides that bare minimum, the following options might also be useful:

• homepage_url: Link to the homepage of the shard. This might not strictly be necessary because it can (and should) be included in the README.
• source_url_pattern: The patterns for source links are currently automatically populated from the output of git remote and only supports public hosting on github.com and gitlab.com. It would be great to provide command line arguments to enable this feature regardless of the current workdir situation and supporting custom hosting providers. Potentially, this should also allow to specify mappings for different paths (see Multi folders crystal doc generation support #8550 (comment)).

Technically, most of this information could usually be extracted automatically from the git workdir and shard.yml. But I believe the doc generator should not be bothered with that. It adds a additional complexity. I'd prefer to keep the docs generator dumb and only accept all these properties as command line arguments. Maybe instead we could add a shards docs command that wraps the compiler docs generator and automatically populates these arguments with values it can read from shard.yml and the git workdir. So shards deals with shard.yml and crystal docs deals with generating docs. That's definitely a separate topic though, just an idea to continue with this. For now I'd like to just add at least the minimum properties to the docs generator. Having to specify them manually as CLI arguments is already an improvement. In the next step we can discuss whether we want it populated automatically by the docs generator or shards. Or some other solution.

Visually, I'd propose to add the name and version (plus optional other data such as homepage_url) at the top of the sidebar. This is an example how it looks in elixir's doc generator:

https://hexdocs.pm/ex_doc/Mix.Tasks.Docs.html

[straight-shoota]

A basic implementation has arrived in #8792 so we can close this issue. Further enhancements are on their way (#9074, #9119) or can be discussed as separate proposals.