Generate documentation for third-party packages similar to https://docs.rs/

[yorickpeterse]

Description

With https://github.com/inko-lang/inko/issues/333 completed, we now have the means to generate documentation for a project.

To make it easier to find documentation for existing projects, we should set up something similar to https://docs.rs/ that generates documentation for a list of projects.

Ideally this tool uses the list of packages found here, such that users don't need to submit their package to two different repositories.

A few challenges/questions present themselves when building this:

• Packages may use syntax/features/etc not supported by idoc. This means we might need a way to specify a minimum version to generate the documentation for
• Cloning each repository, iterating all tags and generating documentation probably won't scale well
• If we upload to Cloudflare R2, we need to set up the necessary caching rules, similar to what we do for the manual and standard library documentation. Using Cloudflare Pages means we have to check-in the generated files into Git, which I'm not a fan of
• If I'm not mistaken, GitHub Actions applies some restrictions in terms of what you can use recurring workflows for. I'm not sure updating the website periodically is actually allowed, since it's technically not used to drive any work on GitHub (e.g. by creating issues)

I feel a push model would be better instead of pulling, but this requires a mechanism by which users can submit a request to generate the documentation for a certain package.

One way we could do this is by tying it into the package list of the website: when the website generator updates the package metadata, it also triggers a CI build to generate the documentation for that project. This way the documentation portal doesn't have to maintain any state. The downside is that we currently only update the package list once a week, which may not be fast enough in the future, though we could allow users to manually submit a request of some sort at some point.

TODO

• [ ] Ensure all packages listed at https://inko-lang.org/packages/ compile with 0.15.0, updating them where necessary
• [ ] Ensure all these packages use the correct Markdown formatting
• [ ] Automatically create an issue if building the documentation fails

Related work

No response

[yorickpeterse]

Regarding the use of recurring workflows, GitHub automatically disables recurring workflows if no repository activity is detected for 60 days: https://docs.github.com/en/actions/learn-github-actions/usage-limits-billing-and-administration#disabling-and-enabling-workflows