BootTidal.hs should automatically update/display the contents of the upstream BootTidal.hs contents

[cleary]

Reported by @ijc8

I wonder if there's a good way to make BootTidal.hs the source of truth for the version embedded in the docs. It's already linked on the page, but the embedded snippet gets out-of-sync with the file it's referencing.

Client-side (runtime) options:

Use JS and fetch().
Use an <iframe>.
Both options ensure that BootTidal will appear up-to-date, but complicate syntax highlighting and make the docs less self-contained.

Server-side (build time) options:

Do something custom to fetch BootTidal.hs at build time and inject it into boottidal.md.
Use snipsync, which has docusaurus integration.
Or perhaps these are all overkill and the occasional PR works well enough.

[cleary]

I ran into the react component that @mindofmatthew created for the youtube embedding. This is likely the type of container we'd need to solve this problem

https://github.com/tidalcycles/tidal-doc/tree/main/src/components/youtube

[Zalastax]

If we want to use an iframe, we need to check that's allowed by Github CDN Cross-Origin Resource Sharing (CORS) or use a CORS bypass proxy. Also applies to fetch() toward the CDN. It seems like the Github REST API allows CORS but unauthenticated access is rate-limited to 60 calls per hour and is associated with the IP.

If I were to implement this, I would write a small script that looks at a cloned Tidal repo and updates this repo through a commit which I can send a PR for. Such method could also be used for generating other documentation, e.g. index of all functions. The snipsync approach is cleaner for the use case in this issue but if we want to expand to more things then perhaps we need more flexibility? Or should we do something similar as snipsync for the other use-cases too?

[matthewkaney]

I think an automatic action to generate PRs against this repo is the way. I didn't ever finish it, but my prototype Haddock-to-Docusaurus conversion would need to run custom server-side code anyway.

I'm not the best at GitHub actions, but I think that /Tidal would need an action that runs on every new release, calling a web hook that runs an action in /tidal-doc that actually pulls the Tidal release and generates docs and so on.

[Zalastax]

Good idea @mindofmatthew!

Unfortunately it seems a bit tricky:
Trigger across repositories requires Personal Access Tokens (PATs): https://stackoverflow.com/a/58468828
And PATs have some issues that are described here: https://shopify.engineering/automatically-rotate-github-tokens

But since the Tidalcycles repo is openly available we can clone without a PAT. And with a periodic trigger we don't need to trigger from a release. We could trigger daily + store & check the hash of the Tidalcycles repo used last time to avoid a rebuild.

Here's how to use a schedule: https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule

Here's how to do the checkout: https://github.com/actions/checkout#Checkout-multiple-repos-side-by-side

Here's how to conditionally skip the job: https://docs.github.com/en/actions/using-jobs/using-conditions-to-control-job-execution

This seems to be how to get file content into a variable: https://stackoverflow.com/a/60679655

To debug actions locally, I have read that https://github.com/nektos/act can be used.