GitHub release that triggers publishing documentation and PyPi package

[erikhuck]

The issues with publishing the documentation upon opening a pull request or merging a pull request into main are that those don't necessarily correlate with a publication to PyPi, meaning the live documentation may not be finalized or it might reflect a later release that has not made its way to PyPi yet. One option to control when the documentation gets published is to use workflow_dispatch. However, it might be possible to do so using GitHub releases.

While I still need to work out the details (including determining if this is even possible), I envision that we could have a GitHub action that's triggered by a release that would:

1. Follow these steps to create a new release and associated tag.
2. The release should trigger a deployment that does the following.
3. Build the package via python -m build
4. Run twine check dist/*
5. Publish the package to testpypi
   1. We'll need testpypi credentials for this. We can possibly get them using GitHub actions
   2. We may want to use organization secrets so that the same credentials can be used across all projects, reducing the amount of configuration done by the developer.
   3. We can use the lab's PyPi credentials i.e. for the MoseleyBioinformaticsLab account.
   4. If the individual developer needs access to manage the PyPi package, then the owner of MoseleyBioinformaticsLab may need to add the developer as an owner rather than the developer adding MoseleyBioinformaticsLab as an owner.
6. If publishing to testpypi succeeds, pip install the testpypi package
7. Using the installed package, run the tests (on all 3 operating systems as usual).
8. If the tests succeed, uninstall the testpypi package and publish the real version of the package.
   1. This will require PyPi credentials in the same way as for testpypi
9. As an extra precaution, install the real version of the package from PyPi and run the tests on the real package.
10. Build the documentation corresponding to the version tag of the release (should be same as for PyPi.
11. Publish the documention to GitHub pages.

We could have a separate .yml file for the documentation and the PyPi / tests. We may want to further re-use actions for running the tests since there is already an action that runs tests that's ran during a pull request. We can have the following:

• tests.yml
• documentation.yml (not triggered, only used by package_release.yml
• package_release.yml re-uses tests.yml (maybe) and documentation.yml

It might be necessary to have an additional .yml file that re-uses tests.yml since when submitting a pull request, we may not only run tests but we also install the package and we do so in a different way than we would in the pypi.yml.

It may be better to use the 0.x.x version when prototyping with testpypi since the first couple of attempts may not work.

This tutorial could be helpful. Looks like we'll want to use the PyPi API token.

[erikhuck]

completed by #37