github actions workflow for publishing documentation

[rscohn2]

Description

Publish documentation to github pages with a github action

Addresses comments from earlier version: #482

[dnhsieh-intel]

Thank you! I really appreciate the PR!

The built documentation looks different (probably the theme?):

Ping @fitchbe for the command to build documentation.

[fitchbe]

Hi, @dnhsieh-intel! I recommend referring to the oneMKL DPC++ reference repo as a model for set-up and build instructions. Regarding themes, the convention is to use the Sphinx "book" theme for Intel-proprietary product documentation on intel.com (IDZ) and the Sphinx "read-the-docs" theme for open-source projects.

[rscohn2]

The conf.py is using sphinx_book_theme, but the doc looks like default alabaster to me. I might be missing a plugin in the install.

[rscohn2]

The built documentation looks different (probably the theme?):

It turns out that the cmake build of the doc was broken. The original 0.1 commit had a conf.py and a conf.py.in. The cmake build used the conf.py.in. After 0.1, there were changes to the conf.py and it is clear that the published documentation was built using it, but not using cmake. I deleted conf.py and put the changes in conf.py.in + some additional changes so the cmake build would work and fixes for some warnings.

There are still some warnings about undefined references. It looks like the API part of the doc needs to be updated.

[rscohn2]

@dnhsieh-intel : Using the current onemkl versions did not work: https://github.com/oneapi-src/oneMKL/actions/runs/9174663052/job/25225986051
I think it would require pinning all the versions, not just the top level.

I installed the latest versions and did a pip freeze to capture all the dependencies in the requirements.txt. Dependabot will keep them up to date.

[dnhsieh-intel]

Big thanks! It worked when I tested on a local machine, probably because the environment is not "clean enough"...

[rscohn2]

@Rbiessy, @mkrainiuk : I think this is ready to merge, but needs another approval