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.

[chrismattmann]

on every push

[chrismattmann]

@afuetterer i changed to "deploy from a branch" in Github settings for this repo as you requested.

[afuetterer]

Alright, lets see if this works. Lets merge this and have a look at the docs. Okay?

[chrismattmann]

Merged, thanks @afuetterer

[afuetterer]

It worked. What do you think about the docs? Improvement?

[chrismattmann]

Yes I love it thank you @afuetterer ! https://chrismattmann.github.io/tika-python/

Thank you for all your contributions so far! do you know why the build isn't passing?

[afuetterer]

Awesome. Maybe you add the page as website under "Edit repository details". You can select "Use your GitHub Pages website".
Otherwise its kind of hard to discover, right?

CI is red, because of HTTP requests getting 429 responses.

[chrismattmann]

I'll add the page in repo details sounds good. how do we fix the build?