Start pushing tags to permanently-kept documentation pages

[GarethCabournDavies]

Here I am starting to put together an idea on how to provide documentation for every release. I.e. instead of only having https://pycbc.org/pycbc/latest/html/, we would have https://pycbc.org/pycbc/v2.4.X/html/ as well, which points to the documentation at that release

Standard information about the request

This change affects continuous integration and the documentation

This change has been proposed using the contribution guidelines

This change will require a new release to ensure that it is correctly enacted

Motivation

This is best practice anyway, but there is an issue at #2504

Contents

• Add a new job to the CI which is only run when a release is made.
• This will also add the documentation to a new folder within the gh-pages repo
• The gh-pages repo should then have the release kept whenever the documentation is built again, and will be pushed for each version

Plan for next steps

• Get a dropdown of links for each version (plus latest) added to the bottom of the sidebar on the documentation pages
• Add a link to the latest released version of the documentation to pypi

Testing performed

I'm not sure how to test this without making a release!

• The author of this pull request confirms they will adhere to the code of conduct

[ahnitz]

@GarethCabournDavies I think this is a long overdue good thing to do. Thank you for looking into this!

[GarethCabournDavies]

I think the only way this can be tested is it it is just merged and see if it runs for the next release

[ahnitz]

@GarethCabournDavies Doesn't this have code duplication here?

[ahnitz]

To further explain, it looks like the documentation release is now duplicated rather than simply running on both master and the tag version.

[GarethCabournDavies]

yeah, I couldnt work out how to move to latest _gh-pages/${GITHUB_REF#refs/tags/} or current (or whatever) dynamically

[ahnitz]

@GarethCabournDavies I don't really follow. Wouldn't you just have an if statement in the yaml in the case of a release and then essentially do what you do here, except without all the duplicated bits?

[GarethCabournDavies]

Ah, I think I didn't realise you can effectively use shell if statements in the yaml, I will try deduplicating