docs: restructure sphinx documentation

[afuetterer]

This will be a longer PR to fix #443.

I will set it to draft for now.

Waiting for related PRs

• waiting for chore: remove obsolete docs #480 to merged
• waiting for chore: reorder .gitignore #483 to merged
• waiting for ci: rename docs workflow #478 to merged
• waiting for build(deps): add dependency-groups #479 to merged
• test: fix coverage reporting #489
• chore: add more informational badges to readme #493

Tasks

• rebase
• add "documentation" to project.urls in pyproject.toml
• remove readme.rst
• include "readme.md" in index.rst
• update docs/source/conf.py
  • add link to github repo (see https://pradyunsg.me/furo/customisation/footer/#configuration)
  • add sphinx-apidoc settings
• add more badges to readme chore: add more informational badges to readme #493
• fix documentation gha workflow
• add docs build to ci to test if a pr breaks the docs?
• workflow call, call from pr as well
• if pr, do not deploy...
• clean up documentation.yml
• fix docstrings in python modules
• clean up conf.py
• squash commits
• configure the GitHub actions workflow as the source of your deployment (needs to be done by @chrismattmann in repo settings)

[coveralls]

coverage: 67.356% (+0.3%) from 67.086% — afuetterer:443-docs into chrismattmann:master

[afuetterer]

For these changes to take effect, please configure the GitHub actions workflow as the source of your deployment. Otherwise you will still have only the readme on your page.

See instructions: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow

[chrismattmann]

For these changes to take effect, please configure the GitHub actions workflow as the source of your deployment. Otherwise you will still have only the readme on your page.

See instructions: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow

I will take a look how to do this this week, thanks @afuetterer the pre-req PRs are now merged.

[afuetterer]

What do you think about the following suggestions?

• Build the docs in ci (e.g. on every pr) to see if something breaks -> skip deploy step
• Build and push/deploy on every commit - now decide on whether push to master or only on tagged versions

[afuetterer]

For these changes to take effect, please configure the GitHub actions workflow as the source of your deployment. Otherwise you will still have only the readme on your page.
See instructions: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow

I will take a look how to do this this week, thanks @afuetterer the pre-req PRs are now merged.

Did you look at this setting?

[afuetterer]

Build and push/deploy on every push to master?
OR just on tagged releases?

Both are fine, I think.