migrate from sphinx

[johrstrom]

We know we want to migrate from Sphinx to something else. We'd looked into https://docusaurus.io/ but https://www.mkdocs.org/ was just suggested as well. I wonder if there are other projects we're missing that may be nice to consider.

┆Issue is synchronized with this Asana task by Unito

[ericfranz]

Repasting here my thoughts shared on Slack.

Editing in Sphinx is a more expensive task than to do so using Markdown. One problem with Sphinx is that the complexity means you really can’t trust yourself to make quick edits using the GitHub inline editor, or quick edits in general. So the documentation doesn’t get updated nearly as often as it could as a result.

https://docusaurus.io/ looked particularly interesting because it has its own “documentation version system” which might possibly be simpler than our custom branching strategy+github actions+docker image though we would still need to use github actions to automate the build. Another consideration was that https://docusaurus.io/ default theme looks better than what we have now on https://openondemand.org/ so then maybe we could use the same tool for both sites with not much effort. Though right now the plan is to outsource work on improving https://openondemand.org/ so we are not distracted from that.

Whatever is done, we want to support the "documentation versioning" scheme we have now - so access to all the older versions of the documentation, and a sane way to maintain multiple versions of the documentation at the same time, with the ability to preview changes made in PRs (what ood-documentation-test serves for us right now).

Switching to a new resource should allow confidently utilizing GitHub's inline editor to make minor documentation edits and be inviting for new people to contribute.

[ericfranz]

Looks like Coldfront is using MkDocs https://coldfront.readthedocs.io/en/latest/. Adopting what they use might be best for the project, especially if XDMoD also adopts the same (then all three projects would have the same look and feel, at least for the documentation). Plus you have access to individuals that are working with it at the same time so they have already thought through some of the problems you will need to figure out. Finally it looks like they have determined a way to handle multiple documentation versions:

https://coldfront.readthedocs.io/en/latest/

So this could literally be a topic of discussion at the next OnDemand meeting, or something you could talk in person with Dori or other ColdFront team members with regards to best practices. Assuming the documentation version management is sane, at this point my recommendation would be MkDocs.