Add `.crystaldoc.yml` config file for configuring docs generator

[nobodywasishere]

Add a .crystaldoc.yml file that lists config options for crystaldoc, namely what apt packages should be installed before executing, and what commands should be executed before building docs. This would allow GTK4 binding docs to be built

https://forum.crystal-lang.org/t/crystaldoc-info-hosted-shard-api-documentation/6018/5?u=nobodywasishere
https://hugopl.github.io/gtk4.cr/

[BlobCodes]

It would also be cool to have a way to canonicalize projects if a .crystaldoc.yml were added.

For example, I mostly host my projects on GitLab and often create GitHub mirrors for greater visibility.
In that case, there are two identical projects on crystaldoc.

Could also help with forks - if a project doesn't un-canonicalize in the .crystaldoc.yml, it's probably only meant for contributions and not very relevant.

[straight-shoota]

@BlobCodes shard.yml has a repository key for exactly this purpose. I don't think there's a need for duplication.

[straight-shoota]

I don't think generating docs should have any requirements except for the source code.

Generating code for documented APIs via macros seems like a very questionable endeavour. Especially if that means the APIs are platform specific. Then a central API documentation doesn't make much sense because it can only represent one version.

A possible workaround could be to have one or multiple shards that each contains the generated code for a specific platform and thus provides API docs for that platform.

The only relevant configuration that could be useful in some cases is a specific file as entry point for the doc generator.

[nobodywasishere]

I don't think generating docs should have any requirements except for the source code.

This wouldn't be a requirement, just a way to provide additional information if your shard needed it in order to build docs.

Generating code for documented APIs via macros seems like a very questionable endeavour.

Not sure what you mean by this

Especially if that means the APIs are platform specific.

Currently the APIs are platform specific, but doing something like docs.rs and providing separate docs per-platform (and not knowing what platforms exactly are supported by the project) would be a headache, and I personally didn't want to deal with it for an MVP (which is what crystaldoc.info still is currently).

Other option could be a way to indicate that certain methods/objects only belong to specific platforms (:platform: darwin or :arch: x86_64 directives?). Would also need to handle cases of the same object being defined twice for different platforms... maybe not.

The only relevant configuration that could be useful in some cases is a specific file as entry point for the doc gerneator.

That may be the case if generating documentation only required the source code, but that's not always true, such as in the Crystal GTK4 bindings.

[straight-shoota]

The question of shards with platform-specific APIs probably deserves a separate discussion. Currently doc generation does not really acknowledge that the same source code could produce different APIs depending on flags and we expect docs to be static.

Generating code for documented APIs via macros seems like a very questionable endeavour.

Not sure what you mean by this

There are multiple issues with mass-generating code at compile time. For example, it makes it impossible to search or link the sources because they're never stored anywhere. It's also not very efficient to generate sources on every build.
Automatic code generation is fine, but I believe it would be benefitial to materialize it and check it into the repository.
We're doing that for a couple of files in the crystal main repo for example: https://github.com/crystal-lang/crystal/blob/099f5723ec30ef720d71bd37389205440acb6b73/.gitattributes#L9-L24

That makes all the source code available without requiring any dependendencies, which enables practically all compiler functions except actual linking. It enables doc generation, but also cross-compilation and code analysis.