SWAPI figures/script updates: CI and GitHub Pages for docs?

[hafarooki]

Currently, docs/swapi can easily end up stale by forgetting to run scripts to regenerate figures. This has been a pain for me lately. I'm thinking it would be better to set up MkDocs or Sphinx with CI for those docs, and have the CI also regenerate the figures. What do you think @jtniehof , @leowerneck ?

[hafarooki]

In the meantime I'm going to make a PR to make the figures deterministic PNGs instead of SVGs which apparently can change a lot when you regenerate them even if there is no change to the actual image....

[hafarooki]

I think figures/script updates are taking a disproportionate amount of time in my WIP PRs. They are not actually necessary for data release because the changes are already validated by the tests. So I am going to defer the figures/script updates for after all the PRs are done into one dedicated PR. This issue now tracks that in addition to the potential process improvement of CI/GitHub pages, which may be bundled into the docs update.

[jtniehof]

A pre-commit hook might be another option for making sure figures are up to date relative to the scripts.

I'd kind of prefer sticking with SVG. Nobody should be reviewing the diff on the SVG :)

[hafarooki]

The SVGs are actually substantially larger than the 8-bit PNGs I switched to on my WIP branch. The SVGs also take surprisingly long to render, which can get annoying. Would you still prefer SVGs?

Regarding pre-commit hooks: a challenge I've encountered with trying to automate this is that the figures take too long to generate. Some of them take >1 minute, most of them take a few seconds. It could be optimized further, but maybe not to the point of being fast enough for a pre-commit hook.

[leowerneck]

I like the idea of having a dedicated Github Actions workflow that generates images and adds them to the repo if everything succeeds.

That being said, I wouldn't mind looking over the plot-generation scripts and see if there are any easy speed ups we could do. If we can get all figures generated in a matter of seconds, I think the pre-commit hook idea would be very viable (and likely preferred).