Description
The PyGMT documentation is hosted in the gh-pages
branch, with docs of each PyGMT release stored in subdirectories, and docs of the main branch in the dev
subdirectory.
Currently, the documentation has no backups and we may lose all the documentation in some rare cases, e.g.,
- Accidentally delete the gh-pages branch when someone tries to clean up stale branches (happened once in the GMT repository Web documentation missing gmt#7338)
- Changes to the "Push the built HTML to gh-pages" step in the "Docs" workflow have uncaught flaws [That's why I'm hesitating to make any changes to improve the step, since it has been working well for a long time]
- "Push the built HTML to gh-pages" step in the "Docs" workflow fails and leads to partial uploads
- maybe more
Technically speaking, we can restore the PyGMT documentation since,
- we may have the gh-pages branch in our local copy (maybe not)
- we can create local environments and rebuild the docs for each PyGMT version [It takes a lot of efforts]
I think the easiest solution is to upload the documentation of each release as release assets. Then if we lose the documentation, we just need to:
- create a new gh-pages branch
- download the documentation for each release from the release page
- organize the documentation into subdirectories and add them to the gh-pages branch
- push the docs to the remote gh-pages branch
- manually trigger the "Docs" workflow once
Looking at the current gh-pages branch, there are more files/directories in addition to the version subdirectories, so the above steps are not enough to restore the gh-pages branch. Here are the additional files/directories:
.buildinfo
: This file was added 6 years ago. At that time, files were pushed to the root directory instead of subdirectories in the gh-pages branch. In other words, this file should be deleted..nojekyll
: Tell GitHub to not build this branch using Jekyll [Automatically created by the workflow]CNAME
: Set up the docs domain (xref: https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/troubleshooting-custom-domains-and-github-pages#cname-errors) [It was manually added and maintained. I think we should create it automatically in the workflow]index.html
: The index page, redirected to/latest/
automatically [Again, this file should be automatically created in the workflow]latest
: Symlink to the latest release [Automatically linked to the latest version only when making a release. So it's likely we have to create the symblink manually, but it's technically possible to determine the latest version usinggh release list
command]dev
: Contains the dev docs [Automatically created by the workflow]
It agreed, here are things we need to do:
- Create a workflow file to upload the documentation as release assets when making a release CI: Upload documentation HTML ZIP archive and PDF file as release assets #3814
- Upload the documentation of old versions to the release page [manually]
- Remove the
.buildinfo
file Delete the .buildinfo file from gh-pages branch #3748 - Improve the step to ensure
.nojekyll
/CNAME
/index.html
are created automatically CI: Update the doc deploy script to generate CNAME and index.html #3749 - See if we can have the
latest
symlink created automatically