Sphinx based documentation

[j-i-l]

closes #2

The package should get a web-based documentation.

The following tasks will be addressed in this pull request:

• Basic structure for a sphinx documentation
• Extracting documentations from docstrings
• Setup of GH actions to deploy the documentation

[j-i-l]

@alexbovet you can checkout the basic styling and rough extract from the docstrings in the 'checks'.

Here is a link to the last one:
https://github.com/alexbovet/flow_stability/suites/18712945827/artifacts/1089308064
simply extract the content of the zip file and open the index.html in your browser.

Questions:

• What should be the styling? Currently the sphinx-book-theme is used see https://sphinx-themes.org/ for others.
• Where should we deploy the site? My suggestion would be on https://readthedocs.org but we can also create a github static page

[alexbovet]

Hey, thanks! I quite like the Insegel theme. What is the advantage of readthedocs vs a github page?

[j-i-l]

Readthedocs is a prominent and free hoster for software documentations, especially for python. Its advantage are the easily accessible features (mostly that's versioning and previews for pull requests). The drawback is yet another service to register, though you can authenticate with GitHub.
With GH pages you have everything in one place (i.e. on GitHub) but versioning and preview features are not (yet?) available for pages. They can, kind of, be implemented with job artifacts, but it's more of a hack.
I would go for readthedocs.

[alexbovet]

Ok for readthedocs then!

[j-i-l]

It seems also to be a good combination:

From https://insegel.readthedocs.io/en/latest/:

The theme [Insegel] itself can be deployed anywhere, but has specific enhancements for hosting on ReadTheDocs.

[j-i-l]

Here is how it looks with Insegel:

https://github.com/alexbovet/flow_stability/suites/18746248617/artifacts/1091735429

[j-i-l]

@alexbovet On ReadTheDocs there is always someone that 'hosts' the documentation. I would recommend that you are the one hosting it. But I'm also fine with hosting it on my account.

If you want to host it, then:

• sign in to readthedocs.org with your github account (or any other sign in method)
• under https://readthedocs.org/dashboard/ click on Import a Project
• import it (the .readthedocs.yml from the 2nd step is already added in this branch)
• once it is added click on the project select Admin > Advanced Settings > check the Build pull requests for this project box and save.

Now we should start to see preview builds in the pull request already.

[alexbovet]

Should I import the main branch?

[j-i-l]

Yes, I would keep it simple.

[alexbovet]

ok done

[j-i-l]

Great!
@alexbovet if you click on Show al checks on the All checks have passed entry, and then on Details on the 8docs/redthedocs.org:... you will see a preview of the docs.

Now we can start to fix-up the docstrings and populate the documentation some more.

[j-i-l]

@alexbovet If this is fine with you, I'd merge this branch into main as it contains a first functioning version of the documentation.
Better formatting the docstrings, adding examples and further details to the documentation can then be done separately.
Alternatively, we can keep on populating the documentation in this branch and merge it only once we are happy with the state of the documentation. The drawback here is only that this branch will then contain edits of most (if not all) *.py files and thus will be less straight forward to merge, if other edits happened in-between.