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 😕

[FabianIsensee]

Thanks for this PR! I like the idea of having proper hosted docs.

One issue though: our development happens on an internal GitLab instance that mirrors all commits to GitHub. The mirror periodically overwrites GitHub's history with whatever is on GitLab. This means the git-auto-commit-action approach won't work. The site/ commit would get wiped on every mirror sync.

The fix would be to deploy to GitHub Pages directly instead of committing site/ back into the repo. This requires two changes:

1. Update the workflow to use Pages deployment actions:
   Replace git-auto-commit-action with upload-pages-artifact + deploy-pages, add the necessary permissions and concurrency blocks, and also add mkdocs.yml to the paths trigger so nav changes also rebuild the docs. Something like:

  name: Build Docs

  on:                                                                                                                                            
    push:
      branches: ["master"]                                                                                                                       
      paths:      
        - 'documentation/**'
        - 'mkdocs.yml'

  permissions:
    pages: write
    id-token: write

  concurrency:
    group: "pages"
    cancel-in-progress: true
                                                                                                                                                 
  jobs:
    build-and-deploy:                                                                                                                            
      runs-on: ubuntu-latest
      environment:
        name: github-pages
        url: ${{ steps.deployment.outputs.page_url }}
      steps:
        - uses: actions/checkout@v4
        - uses: actions/setup-python@v4                                                                                                          
          with:
            python-version: '3.10'                                                                                                               
        - name: Install MkDocs
          run: pip install mkdocs
        - name: Build docs
          run: mkdocs build
        - uses: actions/upload-pages-artifact@v3                                                                                                 
          with:
            path: site/                                                                                                                          
        - id: deployment
          uses: actions/deploy-pages@v4

2. Enable GitHub Pages in the repo settings:
   I'll need to set the Pages source to "GitHub Actions" under Settings -> Pages. Let me know once you've updated the workflow and I'll take care of that.