Skip to content

Upload the documentation as release assets #3731

Closed
@seisman

Description

@seisman

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.

Screenshot from 2024-12-30 15-40-06

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:

  1. create a new gh-pages branch
  2. download the documentation for each release from the release page
  3. organize the documentation into subdirectories and add them to the gh-pages branch
  4. push the docs to the remote gh-pages branch
  5. 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 using gh release list command]
  • dev: Contains the dev docs [Automatically created by the workflow]

It agreed, here are things we need to do:

Metadata

Metadata

Assignees

Labels

maintenanceBoring but important stuff for the core devs

Type

No type

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions