Generate tutorial HTML automatically

[jadephilipoom]

Currently, the workflow for the tutorial page is:

1. someone edits tutorial.v
2. when Jade next wants to edit the tutorial, she regenerates the HTML using her locally installed Alectryon (what version is it? No one but Jade knows) and submits a PR with the new HTML file, at which point the change from (1) appears on the website.

Since the tutorial is public-facing and we've gotten a few edits already from people other than me, I think it would be good if the "generate HTML" step happened automatically when changes to tutorial.v were submitted, e.g. as a github action. This would mean that people's changes get reflected automatically, and our Alectryon version is somewhere everyone can see and replicate.

[blaxill]

I'm not so familiar with the doc workflow but can we have the generated files in a dedicated branch e.g. docs, then in CI for a main PR push to this dedicated branch, does that seem reasonable? Reason being updating the branch that is under going CI is probably not reasonable.

[satnam6502]

For this I think it is fine to manually generate the HTML and git add it?

[jadephilipoom]

Current build instructions:

• install alectryon dependencies following their README
• clone alectryon https://github.com/cpitclaudel/alectryon (I'm at 3b26ed522de533c0f158498c4a408d3825d68f0b but hopefully their main will also work)
• set an enviroment variable ALECTRYON_PATH to the path to your clone
• call make html

[satnam6502]

Thank you. I don't think we need the CI to automatically build the HTML (I am loathed to do anything to slow down the CI further). However, it would be good if the top level Makefile run the Makefile in the demos directory to generate SystemVerilog circuit and run the associated test.

[jadephilipoom]

I don't think we need the CI to automatically build the HTML (I am loathed to do anything to slow down the CI further).

I believe it wouldn't slow down the CI -- if I understand correctly, the CI builds the core library and then builds the various subdirectories in parallel. This would be another pass that happens on top of the core library -- unless it's the very slowest of those targets, which it definitely isn't anywhere near right now, it won't be on the critical path.