Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add .crystaldoc.yml config file for configuring docs generator #8

Open
nobodywasishere opened this issue Sep 26, 2023 · 5 comments
Open
Labels
enhancement New feature or request

Comments

@nobodywasishere
Copy link
Owner

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/

@nobodywasishere nobodywasishere added the enhancement New feature or request label Sep 26, 2023
@BlobCodes
Copy link

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
Copy link

straight-shoota commented Nov 29, 2024

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

@straight-shoota
Copy link

straight-shoota commented Nov 29, 2024

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
Copy link
Owner Author

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).

image

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
Copy link

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

3 participants