Open cleary opened 10 months ago
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 . Both options ensure that BootTidal will appear up-to-date, but complicate syntax highlighting and make the docs less self-contained.</p> <p>Server-side (build time) options:</p> <p>Do something custom to fetch BootTidal.hs at build time and inject it into boottidal.md. Use <a rel="noreferrer nofollow" target="_blank" href="https://github.com/temporalio/snipsync">snipsync</a>, which has <a rel="noreferrer nofollow" target="_blank" href="https://github.com/temporalio/docusaurus-plugin-snipsync">docusaurus integration</a>. Or perhaps these are all overkill and the occasional PR works well enough.</p> </blockquote> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/cleary"><img src="https://avatars.githubusercontent.com/u/2577966?v=4" />cleary</a> commented <strong> 9 months ago</strong> </div> <div class="markdown-body"> <p>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</p> <p><a href="https://github.com/tidalcycles/tidal-doc/tree/main/src/components/youtube">https://github.com/tidalcycles/tidal-doc/tree/main/src/components/youtube</a></p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/Zalastax"><img src="https://avatars.githubusercontent.com/u/908496?v=4" />Zalastax</a> commented <strong> 9 months ago</strong> </div> <div class="markdown-body"> <p>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.</p> <p>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?</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/matthewkaney"><img src="https://avatars.githubusercontent.com/u/911429?v=4" />matthewkaney</a> commented <strong> 9 months ago</strong> </div> <div class="markdown-body"> <p>I think an automatic action to generate PRs against this repo is the way. I didn't ever finish it, but my <a href="https://github.com/mindofmatthew/tidal-doc/tree/doc-gen">prototype Haddock-to-Docusaurus conversion</a> would need to run custom server-side code anyway.</p> <p>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.</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/Zalastax"><img src="https://avatars.githubusercontent.com/u/908496?v=4" />Zalastax</a> commented <strong> 9 months ago</strong> </div> <div class="markdown-body"> <p>Good idea @mindofmatthew!</p> <p>Unfortunately it seems a bit tricky: Trigger across repositories requires Personal Access Tokens (PATs): <a href="https://stackoverflow.com/a/58468828">https://stackoverflow.com/a/58468828</a> And PATs have some issues that are described here: <a href="https://shopify.engineering/automatically-rotate-github-tokens">https://shopify.engineering/automatically-rotate-github-tokens</a></p> <p>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.</p> <p>Here's how to use a schedule: <a href="https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule">https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule</a></p> <p>Here's how to do the checkout: <a href="https://github.com/actions/checkout#Checkout-multiple-repos-side-by-side">https://github.com/actions/checkout#Checkout-multiple-repos-side-by-side</a></p> <p>Here's how to conditionally skip the job: <a href="https://docs.github.com/en/actions/using-jobs/using-conditions-to-control-job-execution">https://docs.github.com/en/actions/using-jobs/using-conditions-to-control-job-execution</a></p> <p>This seems to be how to get file content into a variable: <a href="https://stackoverflow.com/a/60679655">https://stackoverflow.com/a/60679655</a></p> <p>To debug actions locally, I have read that <a href="https://github.com/nektos/act">https://github.com/nektos/act</a> can be used.</p> </div> </div> <div class="page-bar-simple"> </div> <div class="footer"> <ul class="body"> <li>© <script> document.write(new Date().getFullYear()) </script> Githubissues.</li> <li>Githubissues is a development platform for aggregating issues.</li> </ul> </div> <script src="https://cdn.jsdelivr.net/npm/jquery@3.5.1/dist/jquery.min.js"></script> <script src="/githubissues/assets/js.js"></script> <script src="/githubissues/assets/markdown.js"></script> <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.4.0/build/highlight.min.js"></script> <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.4.0/build/languages/go.min.js"></script> <script> hljs.highlightAll(); </script> </body> </html>
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 . Both options ensure that BootTidal will appear up-to-date, but complicate syntax highlighting and make the docs less self-contained.</p> <p>Server-side (build time) options:</p> <p>Do something custom to fetch BootTidal.hs at build time and inject it into boottidal.md. Use <a rel="noreferrer nofollow" target="_blank" href="https://github.com/temporalio/snipsync">snipsync</a>, which has <a rel="noreferrer nofollow" target="_blank" href="https://github.com/temporalio/docusaurus-plugin-snipsync">docusaurus integration</a>. Or perhaps these are all overkill and the occasional PR works well enough.</p> </blockquote> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/cleary"><img src="https://avatars.githubusercontent.com/u/2577966?v=4" />cleary</a> commented <strong> 9 months ago</strong> </div> <div class="markdown-body"> <p>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</p> <p><a href="https://github.com/tidalcycles/tidal-doc/tree/main/src/components/youtube">https://github.com/tidalcycles/tidal-doc/tree/main/src/components/youtube</a></p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/Zalastax"><img src="https://avatars.githubusercontent.com/u/908496?v=4" />Zalastax</a> commented <strong> 9 months ago</strong> </div> <div class="markdown-body"> <p>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.</p> <p>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?</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/matthewkaney"><img src="https://avatars.githubusercontent.com/u/911429?v=4" />matthewkaney</a> commented <strong> 9 months ago</strong> </div> <div class="markdown-body"> <p>I think an automatic action to generate PRs against this repo is the way. I didn't ever finish it, but my <a href="https://github.com/mindofmatthew/tidal-doc/tree/doc-gen">prototype Haddock-to-Docusaurus conversion</a> would need to run custom server-side code anyway.</p> <p>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.</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/Zalastax"><img src="https://avatars.githubusercontent.com/u/908496?v=4" />Zalastax</a> commented <strong> 9 months ago</strong> </div> <div class="markdown-body"> <p>Good idea @mindofmatthew!</p> <p>Unfortunately it seems a bit tricky: Trigger across repositories requires Personal Access Tokens (PATs): <a href="https://stackoverflow.com/a/58468828">https://stackoverflow.com/a/58468828</a> And PATs have some issues that are described here: <a href="https://shopify.engineering/automatically-rotate-github-tokens">https://shopify.engineering/automatically-rotate-github-tokens</a></p> <p>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.</p> <p>Here's how to use a schedule: <a href="https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule">https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule</a></p> <p>Here's how to do the checkout: <a href="https://github.com/actions/checkout#Checkout-multiple-repos-side-by-side">https://github.com/actions/checkout#Checkout-multiple-repos-side-by-side</a></p> <p>Here's how to conditionally skip the job: <a href="https://docs.github.com/en/actions/using-jobs/using-conditions-to-control-job-execution">https://docs.github.com/en/actions/using-jobs/using-conditions-to-control-job-execution</a></p> <p>This seems to be how to get file content into a variable: <a href="https://stackoverflow.com/a/60679655">https://stackoverflow.com/a/60679655</a></p> <p>To debug actions locally, I have read that <a href="https://github.com/nektos/act">https://github.com/nektos/act</a> can be used.</p> </div> </div> <div class="page-bar-simple"> </div> <div class="footer"> <ul class="body"> <li>© <script> document.write(new Date().getFullYear()) </script> Githubissues.</li> <li>Githubissues is a development platform for aggregating issues.</li> </ul> </div> <script src="https://cdn.jsdelivr.net/npm/jquery@3.5.1/dist/jquery.min.js"></script> <script src="/githubissues/assets/js.js"></script> <script src="/githubissues/assets/markdown.js"></script> <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.4.0/build/highlight.min.js"></script> <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.4.0/build/languages/go.min.js"></script> <script> hljs.highlightAll(); </script> </body> </html>
Reported by @ijc8