Support multi-versioned documentation

[Andy-Grigg]

OpenAPI common still uses the old way of hosting documentation, with non-versioned documentation hosted from a separate repository. We should migrate to the new way of doing things:

• Move the documentation to this repository, and archive the old repository
• Use the Ansys doc-publish actions for production and dev
• Decide whether to publish old versions of the docs

[ludovicsteinbach]

As of today: the main branch is configured to deploy the docs to the gh-pages branch in this repository, using the Ansys deploy actions. This currently is exposed as https://ansys.github.io/openapi-common/

If we were to switch the CNAME to https://openapi.docs.pyansys.com/, we could redeploy the dev docs relatively easily, but we'd lose the existing stable docs for 2.0.1.
We should be able to copy the 2.0.1 docs from the other repo and into the gh-pages branch here, provided that we define the file structure correctly to ensure the version switcher works as expected.

Alternatively, we can wait for the next release, and switch the CNAME before releasing then.

[Andy-Grigg]

I would suggest we do a .post0 release, but we know the documentation action doesn't handle releases with any kind of modifier. I also don't really want to do another patch just to fix the documentation, but I suppose there's nothing stopping us doing that?

How complicated do you think it would be to copy the docs over manually? Are there any changes required to make it work, or is it literally just copying between two repos?

[ludovicsteinbach]

I have had a look, it's not a simple copy paste. There is some additional work required, mainly around making sure each version is at the right place and is aware that there are other versions, and I'm not sure how extensive that is.

For some reason the links are not relative in the generated index, so we'd probably need to first switch the CNAME then redeploy both dev and 2.0.X (stable) as multiversioned.

[Andy-Grigg]

In that case, maybe we cherry-pick this change into the release/2,0 branch and do a patch release?

We can then always go back and do the same cherry pick onto older release branches if we want.

[ludovicsteinbach]

This would work.

• PR to change the CNAME in this repo to https://openapi.docs.pyansys.com/. On merge, will deploy dev docs. Current stable 2.0.1 docs will disappear (Update CNAME to support publishing documentation from this repository #577)
• Bump main to 2.1.0 to ensure there is 2.1 dev version, with the correct URLs in version switcher. On merge, will deploy dev docs (Bump version to 2.1.0 #578)
• Cherry pick actions PR and CNAME update PR into release/2.0 and bump to version 2.0.2 (Prepare release 2.0.2 #579)
• Push tag, CI should add a stable version to the docs
• Archive https://github.com/ansys/openapi-common-docs

[Andy-Grigg]

That sounds good to me!

[Andy-Grigg]

I'm going to close this ticket as complete. I don't think there's much benefit in publishing old versions of the documentation for this repository; the public API really hasn't changed all that much. If we decide we want to do that at some point though, we can always go back and create a new ticket.

Thanks @ludovicsteinbach for getting this sorted!