scirpy
scirpy copied to clipboard
scverse
improve docs build system
Current list of stuff to solve:
- [x] build an overview page of available versions (see also #267)
- [ ] move docs to separate repo to keep footprint small (?)
- ~~[ ] remove PR builds on merge/close~~ (not necessary anymore, as PR docs are not uploaded to gh-pages anymore)
- [x] Fix version number indicated in docs sidebar
- [x] find a way to enable PR doc previews for forks or disable it for forks altogether (It is now disabled, and instead uploads the built docs as an artifact (#277) )
- [x] point the latest tag version instead of the master branch per default.
- [ ] build tutorials in parallel
- [ ] Can parts of this be externalized into github action modules?
Original message
The git push fails with permission denied, despite an access token being provided. Maybe it uses the secrets from the fork instead of the main repo.
Since RTD now fully supports PR builds, it may be worth switching to that service: https://docs.readthedocs.io/en/stable/guides/autobuild-docs-for-pull-requests.html
this also solves versioning of docs and having a separate master and stable documentation.
This will serve to redirect the old docs to the new one: https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/creating-a-custom-404-page-for-your-github-pages-site
and
<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="refresh" content="0;url={{THE_NEW_URL}}" />
<link rel="canonical" href="{{THE_NEW_URL}}" />
</head>
<body>
<h1>
The page been moved to <a href="{{THE_NEW_URL}}">{{THE_NEW_URL}}</a>
</h1>
</body>
</html>
After some tryouts I ran into the issue that RTD does not provide us with enough time and RAM to execute the tutorials.
I considered rtds-action to execute the notebooks on GH actions, but it currently does not support integration with pull-requests (https://github.com/dfm/rtds-action/issues/1).
Therefore, for now I will stick with github actions. It also allows parallel builds or more tutorials in the future. I just need to figure out
- delete old PR builds to clean up the
gh-pagesbranch - point the latest tag version instead of the master branch per default.
- find a way to enable PR doc previews for forks or disable it for forks altogether.
- Bonus: build an overview page of available versions
https://github.com/scverse/cookiecutter-scverse/issues/40 might be a better solution