[DOCU] Add gh-pages using f.e. Sphinx or McDocs

[rojberr]

User Story:

As a developer or user,
I want comprehensive project documentation published via GitHub Pages,
So that I can easily understand, use, and contribute to the project without searching through code or asking maintainers.

---

Acceptance Criteria:

1. Documentation framework chosen and installed (MkDocs or Sphinx)
2. Basic documentation structure created (Getting Started, API Reference, Guides)
3. GitHub Actions workflow for building/publishing to gh-pages branch
4. Documentation automatically deployed on push to main
5. Custom domain support configured (if applicable)
6. Documentation linked from project README

---

Definition of Done:

• All acceptance criteria met
• Documentation build passes without warnings
• Site accessible at https://<org>.github.io/<repo>
• At least 3 core pages populated with content
• Team can update docs via markdown files

---

[rojberr]

Example Implementation:

Implementation Options:

Option 1: MkDocs (Recommended for Simplicity)

# mkdocs.yml
site_name: Project Documentation
theme: material
nav:
  - Home: index.md
  - Getting Started:
      - Installation: getting-started/installation.md
      - Configuration: getting-started/configuration.md
  - API Reference: api.md
  - Contributing: contributing.md
Option 2: Sphinx (Recommended for Python Projects)

python
# docs/conf.py
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
html_theme = 'furo'
Implementation Plan:
Setup Documentation Framework:

bash
# For MkDocs
pip install mkdocs mkdocs-material
mkdocs new .

# For Sphinx
pip install sphinx furo
sphinx-quickstart docs
Create Basic Structure:

docs/
├── index.md           # Homepage
├── getting-started/   # Tutorials
├── api/               # API reference
├── guides/            # How-to guides
└── resources/         # Additional materials
GitHub Actions Workflow (.github/workflows/gh-pages.yml):

yaml
name: Deploy Docs
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.x'
      - run: pip install mkdocs  # or sphinx
      - run: mkdocs build  # or sphinx-build docs build
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site  # Output directory
Custom Domain Setup:

Create CNAME file in docs directory:

docs.yourproject.com
Configure DNS to point to <org>.github.io

Documentation Structure Requirements:
Essential Pages:

Homepage: Project overview and quick links

Installation: Setup instructions

Configuration: Environment setup and options

API Reference: Auto-generated code documentation

Contributing: Development guidelines

FAQ: Common troubleshooting

Content Standards:

All pages in Markdown (.md) format

Code examples in all guides

Version warning for main/unstable branches

Dark/light mode support