Add generated documentation

[johannesjh]

Documentation enhancements: The following two documentation enhancements would be nice to have. Both require setting up of some sort of documentation generator:

• It would be nice to auto-generate the commandline usage. A quick research about tools that we could use for this:
  • shinx-argparse which has recent commits, or
  • https://pythonhosted.org/sphinxcontrib-autoprogram/
• It would be nice to replace the hand-written example (in the README file, section "programmatic usage") with code from a test case... the test case would ensure that the example keeps up to date.

Tooling: Both enhancements require some sort of documentation generator such as sphinx. The generator should run locally and in github ci. Updates to the master branch should automatically update the documentation. Documentation for tagged commits should also be available. Documentation generators such as sphinx are probably able to do these jobs nicely out of the box... we just need to set things up.

• documentation generator:
  • sphinx? pdoc3?
  • sphinx doctest could maybe validate that example code works correctly
• runtime:
  • locally, a simple poetry run sphinx-build ... or tox run -e docs sphinx-build ... should do the job
  • on github ci, we could use the same call. alternatively, we could use the github actions as documented by sphinx under publishing your html documentation

[johannesjh]

Update, I started working on this.

• I added sphinx-doc
• I found a way to include the main README file into the sphinx documentation
• I added pre-commit hooks to make sure the python code is well-documented (and I consequently added a lot of missing docstrings).
• I used sphinx-argparse to automatically document commandline usage
• the programmatic usage example is protected by a regression test.

Todos, to be tracked in follow-up tickets:

• reviewing and improving the documentation.
• it only runs locally for now, I have not added any github ci yet.