Frequency of updating online docs

[CasperWA]

Should we update the online documentation every time we push to master instead of only updating the documentation when publishing a new release?

Since a lot of updates (should be / are) coming to the documentation, it may be nice to see those changes implemented right away in the online documentation when merged.

Note, this may or may not present an issue for the publish workflow if implemented, it should be tested whether the documentation is still built after a publish workflow has run.

[ml-evs]

It would be nice to have stable and master versions of the docs, if its not too much of a pain to sort through gh pages. However, I don't see this being much of a problem in the longer term once we've "finished", so maybe we should just spam releases after almost every PR at the moment?

[CasperWA]

It would be nice to have stable and master versions of the docs (...)

Indeed, something similar to the versioned/git refs-based docs found (through Sphinx?), at least on the readthedocs type documentation.

However, I don't see this being much of a problem in the longer term once we've "finished", so maybe we should just spam releases after almost every PR at the moment?

I don't know. Both yes and no. I don't want to spam just to update the docs ... On the other hand, we should definitely make a release again soon with all the changes.

Also, I am not sure this will ever be "finished", in the sense that there is always something to work on when it comes to docs.

[CasperWA]

After reading up on things a bit, I highly suggest we move to ReadTheDocs for this. It supports versioning, as well as custom URLs. So we can get the documentation out as soon as it's updated, instead of only when we publish a new version. As well as see the documentation at different stages for different version.

Either that or we setup a workflow that pushes the documentation each time a push to master is performed. I would suggest this approach only if we don't care about seeing the documentation at different versions. Which may be fair enough.

[ml-evs]

+1 for readthedocs, they recently added nice new integration with statuses/checks in GH

[CasperWA]

+1 for readthedocs, they recently added nice new integration with statuses/checks in GH

Great.
As I wrote though, I don't consider it a necessity if we don't want the ability to browse the documentation of different states of this package. However, I could see why one may want to read the "latest" version and then the latest versioned release version, i.e., the documentation of master vs. the one of (currently) v0.11.0.

[CasperWA]

I am going to start deploying on readthedocs now.

[CasperWA]

Concerning different versions while still using the MkDocs material theme, I found this issue that basically says "material is not going to support several doc versions natively".

A workaround/hack is proposed and the mike project is mentioned as well.

mike is a "wrapper" for MkDocs, essentially, that is built for gh-pages to create the different versions of branches and tags once, store it in the gh-pages branch and that's essentially it.
So we could choose not to move to RTD and instead use mike, or we can try and hack together a solution for material that implements links to the different documentation versions.

[CasperWA]

In a video call, @ml-evs and I briefly discussed this issue, suggesting that we do nightly builds of the docs with two different versions: "latest" and "stable", referring to the master branch and the latest release, respectively.