feature/mx-1347 Configure gh pages (#11)

# Added
- sphinx configuration and documentation workflow

.github/workflows/documentation.yml

@@ -0,0 +1,80 @@
+name: Documentation
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+env:
+  PIP_NO_OPTION: on
+  PIP_NO_CLEAN: on
+  PIP_PREFER_BINARY: on
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 1
+
+      - name: Cache requirements
+        uses: actions/cache@v3
+        env:
+          cache-name: cache-requirements
+        with:
+          path: ~/.cache/pip
+          key: ${{ env.cache-name }}-${{ hashFiles('requirements.txt') }}
+          restore-keys: |
+            ${{ env.cache-name }}-
+
+      - name: Cache poetry
+        uses: actions/cache@v3
+        env:
+          cache-name: cache-poetry
+        with:
+          path: ~/.cache/pip
+          key: ${{ env.cache-name }}-${{ hashFiles('poetry.lock') }}
+          restore-keys: |
+            ${{ env.cache-name }}-
+
+      - name: Setup python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+
+      - name: Setup pages
+        uses: actions/configure-pages@v3
+
+      - name: Install requirements
+        run: make install
+
+      - name: Run sphinx
+        run: make docs
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: ./docs/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - cve scan workflow
 - CHANGELOG file
 - cruft template link
+- sphinx configuration and documentation workflow
 
 ### Changes
 

Makefile

@@ -14,8 +14,16 @@ hooks:
 	fi; \
 
 install: setup hooks
+	# run the poetry installation with embedded virtual environment
+	@ echo installing package; \
+	poetry install --no-interaction --sync; \
 
 linter:
 	# run the linter hooks from pre-commit on all files
 	@ echo linting all files; \
 	pre-commit run --all-files; \
+
+docs:
+	# use sphinx to auto-generate html docs from code
+	@ echo generating docs; \
+	poetry run sphinx-build -aE -b dirhtml docs docs/dist; \

docs/conf.py

@@ -0,0 +1,7 @@
+# sphinx configuration
+
+extensions = ["myst_parser"]
+html_theme = "alabaster"
+project = "mex-model"
+source_suffix = {".md": "markdown"}
+templates_path = ["."]

docs/layout.html

@@ -0,0 +1,18 @@
+{% extends '!layout.html' %}
+
+{% block footer %}
+    <div class="footer">
+        <a href="https://www.rki.de/DE/Content/Forsch/MEx/MEx_inhalt.html" rel="nofollow">
+            MEx Project
+        </a> |
+        <a href="https://www.rki.de/DE/Service/Impressum/impressum_node.html" rel="nofollow">
+            RKI Imprint
+        </a> |
+        <a href="https://docs.github.com/site-policy/privacy-policies/github-privacy-statement" rel="nofollow">
+            GitHub Privacy
+        </a> |
+        <a href="https://docs.github.com/en/site-policy/privacy-policies/github-cookies" rel="nofollow">
+            GitHub Cookies
+        </a>
+    </div>
+{% endblock %}

mex.bat

@@ -4,6 +4,7 @@ set target=%1
 
 if "%target%"=="install" goto install
 if "%target%"=="test" goto test
+if "%target%"=="docs" goto docs
 echo invalid argument %target%
 exit /b 1
 
@@ -30,3 +31,10 @@ exit /b %errorlevel%
 echo linting all files
 pre-commit run --all-files
 exit /b %errorlevel%
+
+
+:docs
+@REM use sphinx to auto-generate html docs from code
+echo generating conceptual model docs
+poetry run sphinx-build -aE -b dirhtml docs docs\dist
+exit /b %errorlevel%

poetry.toml

@@ -0,0 +1,2 @@
+[virtualenvs]
+in-project = true

pyproject.toml

@@ -8,6 +8,13 @@ license = "MIT"
 repository = "https://github.com/robert-koch-institut/mex-model"
 packages = [{ include = "mex" }]
 
+[tool.poetry.dependencies]
+python = "^3.11"
+
+[tool.poetry.group.dev.dependencies]
+myst-parser = "^2.0.0"
+sphinx = "^7.2.6"
+
 [tool.cruft]
 template = "https://github.com/robert-koch-institut/mex-template"