add MkDocs configuration and build workflow for documentation

[Borda]

Motivation

This PR introduces MkDocs for building and hosting the project's documentation. Previously, documentation was stored as plain Markdown files in the documentation/ directory, which limited discoverability and navigation for users. By compiling these into a structured HTML site using MkDocs, we enhance user experience with features like search, themes, and organized sections (e.g., Getting Started, Advanced Topics). This makes the docs more accessible and professional, aligning with modern open-source standards.

Impact

• Improved User Experience: Compiled docs provide better navigation and readability compared to raw MD files, potentially increasing adoption and contributions.
• Maintenance: Centralized configuration in mkdocs.yml simplifies updates and ensures consistency.
• No Breaking Changes: Existing MD files remain intact; this only adds build tooling.
• Performance: Minimal overhead, as MkDocs generates static sites efficiently.

Simple Guide to Enable Deployment with GitHub Pages

1. In your repository settings, go to Pages under the Code and automation section.
2. Set the source to GitHub Actions (this assumes the workflow pushes to a gh-pages branch or deploys directly).
3. Ensure the MkDocs workflow (e.g., .github/workflows/docs.yml) builds and deploys the site/ directory. If using the stefanzweifel/git-auto-commit-action, it should handle pushing to the repo.
4. After merging, visit https://<username>.github.io/<repo-name>/ to view the live docs. Update the workflow if needed to trigger on pushes to main.

[Borda]

@FabianIsensee, how are you doing? Could you pls have a look? 🦩

[Borda]

@FabianIsensee I do appreciate your work (as you recently made a few commits, which makes me full of hope this repo is not stale yet), and you considered reviewing my contribution, assigning it to yourself, but curious as it has hung for a few months by now, if anything is going to happen, or shall I just close it 😕