Add swagger to readthedocs

[lcaouen]

Add a CI to upload swagger.json as an artifact.

The artifact can be used in readthedocs to generate the documentation.

The Phoebus readthedocs project must be modified as follow to generate the final html :

• add sphinxcontrib-openapi==0.8.4 in the requirements.txt
• enable the extensions = ['sphinxcontrib.openapi'] in conf.py
• use a pre-build section in .readthedocs.yaml to download the latest swagger.json artifact in the "docs/source" folder and to make it available to the readthedocs batch (https://github.com/actions/download-artifact)
• add the directive .. openapi:: swagger.json into a rst file

Here is the documentation : https://sphinxcontrib-openapi.readthedocs.io/

There is also a second plugin https://sphinxcontrib-redoc.readthedocs.io/en/stable/ but the first one uses the standard theme

Here is a preview made locally

[kasemir]

Add a CI to upload swagger.json as an artifact.
The artifact can be used in readthedocs to generate the documentation.
use a pre-build section in .readthedocs.yaml to download the latest swagger.json artifact

No problem having GitHub CI create some optional artifact, which is the purpose of this PR.

As to a follow-up PR to then use that artifact:
Phoebus should continue to support building it locally.
OK, we rely on maven to somehow locate *.jar files, but ideally that's done once, and from then on you can rebuild locally as you work on the source code.
Building the "help" pages included in the product is one step in the build. Right now that help text is generated from *.rst and javadoc, all available locally. The build process should not rely on a swagger.json that it needs to download from GitHub each time.

Maybe this means slightly different configurations for the help pages built into the product and what's on https://control-system-studio.readthedocs.io/en/latest/. The product continues to support a local, offline build, and contains help pages relevant to the product. The https://control-system-studio.readthedocs.io/en/latest/ website has information about REST interfaces which don't need to be in the end-user product.

[shroffk]

Maybe this means slightly different configurations for the help pages built into the product and what's on https://control-system-studio.readthedocs.io/en/latest/. The product continues to support a local, offline build, and contains help pages relevant to the product. The https://control-system-studio.readthedocs.io/en/latest/ website has information about REST interfaces which don't need to be in the end-user product.

This makes sense to me.

The end user help need not include a lot of things which we might still want to publish on the readthedocs