Investigate doc building with workflow

[flying-sheep]

If RTD was a GitHub app, it would be super simple, but the way it is, maybe setting up sphinx-action + GitHub pages is easier? We could check.

Of course RTD has other advantages, such as /latest/ vs /stable/ and so on, which shouldn’t be ignored

[grst]

Last time I used such an approach, there were two downsides:

• it's hard to keep multiple versions
• github actions dont run on PRs from forks

But maybe there are solutions for this by now

[flying-sheep]

Yeah, I was inspired by the workflow that came with the Markdown presentation tool Marp, because of its simple PR preview support. It works like this:

1. configure GH pages the old way (deploy by pushing to gh-pages branch)
2. build docs
3. In PRs, rossjrw/pr-preview-action updates a directory in the gh-pages branch called pr-previews
4. On the main branch, things are just deployed to the root of the gh-pages branch, ignoring the pr-previews directory

Future changes regarding forks:

• The fork problem can apparently be solved and will be in the preview action: Parametrise PR values rossjrw/pr-preview-action#6
• GitHub is working on its own PR preview mechanism for GH pages: preview timeline? actions/deploy-pages#180

Due to the security issues of the first approach, waiting for the second one is probably best.

[grst]

The native github preview mechanism sounds promising. Do you also have a solution for keeping different versions (and linking to them from the documentation)?
Afaik readthedocs somehow injects the version picker into the docs website after it is already built, which allows to pick newer versions from older docs.

I used to have something like that in scirpy before I moved to RTD, using some javascript hacks, but it wasn't the most elegant solution: https://github.com/scverse/scirpy/blob/6ccaa6673d3d043e1e7988e5c92c037ad2ffc713/docs/versions.rst?plain=1#L13-L21