Docs Build Broken and Confusing

[Oglopf]

I went to do some work on the docs today on a separate machine and was appalled how complicated this setup is for a fresh run. Even with ruby and rake and docker the instructions failed and the error message was cryptic. It worries me that any user who goes to make changes will be quickly discouraged.

Digging into this there's another repo that handles the docs build. I was hoping to find a test build there to ensure things work right, but while there is a github action setup for this, the workflow seems to never run. Why is that?

It's also odd because now i've got an issue spread across 2 repos, i need to build the docs, but i need to check the doc-build-repo to do this? It's confusing and likely to attract issues to this repo that should be there (this issue is partially an example).

I'd like to spend some time with a student and other dev to walk through this and watch and see how simple it is, and then see what we can do to improve on it. Plus, maybe I'm the fool and these are simple to build and I'm missing something.