Add sphinx documentation for Python bindings and GitHub action workflow to push to GitHub pages

[hakonhagland]

Builds on #5242 which should be merged first.

Added sphinx documentation for the opm.simulators.BlackOilSimulator Python module. Also added GitHub action workflow to deploy the documentation to GitHub Pages.

For this to work, someone with admin rights for the opm-simulators GitHub repository has to go to https://github.com/OPM/opm-simulators and then to the menu Settings->Pages and set the branch name for deployment to gh-pages, see screenshot below:

See also: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site

[blattms]

Under what url would the documentation appear? Where would something from opm-common appear?

Will this always be the documentation for current master? Would we have release documentation on the side?

[hakonhagland]

Under what url would the documentation appear?

@blattms I believe it will appear at something like https://opm.github.io/opm-simulators/

Where would something from opm-common appear?

I think: https://opm.github.io/opm-common/

[hakonhagland]

Rebased

[hakonhagland]

jenkins build this please

[hakonhagland]

jenkins build this please

[akva2]

I don't have settings access so I can't active it but this looks good to me at least.

[hakonhagland]

Will this always be the documentation for current master? Would we have release documentation on the side?

@blattms Good point, I did not think about versions. I think we can get versioning with GitHub pages, see for example: https://github.com/devanshshukla99/sphinx-versioned-docs and https://www.codingwiththomas.com/blog/my-sphinx-best-practice-for-a-multiversion-documentation-in-different-languages. But it seems like it is not very commonly used? Maybe we should try Read the Docs instead? Since they appear to have a more well established workflow for versioning? @vkip What do you think?

[hakonhagland]

Will this always be the documentation for current master? Would we have release documentation on the side?

@blattms I played a little bit with https://github.com/devanshshukla99/sphinx-versioned-docs and I think we can use this to get versioned docs. We have to tag the commits we want to include, then the sphinx build will collect the versions from those commits. After the build is completed, all versions will then be included in the sphinx _build directory. When we upload this directory to GitHub pages there will be a version selector at the front page similar to the one used at readthedocs. The user can then select the version of the documentation they want to view from that selector.

[vkip]

... @vkip What do you think?

No real strong opinion here. As you mention RTD versioning is well established, but as long as it works this is fine by me.

[hakonhagland]

@vkip, @akva2, and @blattms I added a new commit to address the versioning, see: 69d3d6c

[hakonhagland]

jenkins build this please

[blattms]

Dumb questions from me:

• Is this action executed for each merge?
• Is there any version information on the generated pages (e.g. commit or date)?

I know it is surprising if you see how I behave in this project 😅, but I do not have any admin power here. Seems like only @alfbr, @atgeirr, or @totto82 can change settings.

[hakonhagland]

Is this action executed for each merge?

@blattms It is executed for each merge/push to the master branch but only if anything inside the python folder was changed.

Is there any version information on the generated pages (e.g. commit or date)?

We can choose to tag certain commits (e.g. releases) and have those included in the version selector in the lower left corner of the page. Here is an example from another GitHub page:

This page has included versions for git tags "v0.1", "v1.0", "v1.1", and "v1.2" and for the current head of the "main" branch. The currently "active" documentation among those versions is the "main" as indicated with green color.

Let me know if we need more information than this tag information.

[totto82]

Can we merge this? Or will this interfere with the release process?