Docs deployment auf Github-Pages mit mkdocs

MkDocs installieren

pip install mkdocs mkdocs-material

Verwendung des Proxy

In der Schule muss Python die Verwendung des Proxy mittgeteilt werden. Dies geschieht durch die Option --proxy. Der resultierende Befehl sieht also wie folgt aus:

pip --proxy http://kjs-03.lan.dd-schulen.de:3128  install mkdocs mkdocs-material

Mit mkdocs anfangen

Zuerst muss man eine mkdocs.yml Datei anlegen, die die Struktur und das Aussehen der Dokumentation beschreibt. Ein Beispiel könnte wie folgt aussehen:

site_name: Projektname
nav:
  - index.md
theme: material
markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

Dazu benötigt man eine Verzeichnisstruktur wie folgt:

Projektverzeichnis
 |- mkdocs.yml
 \- docs
  \- index.md

Dokumentationen Lokal ansehen

Dazu führt man mkdocs mit dem Unterbefehl serve wie folgt aus

mkdocs serve

Befehl konnte nicht gefunden werden

Falls mkdocs installiert ist, es aber von der Git Bash nicht gefunden werden kann, ist es wahrscheinlich nicht im PATH enthalten. Für diesen Fall muss der Befehl mkdocs durch folgenden Befehl ersetzt werden:

~/AppData/Roaming/Python/Python310/Scripts/mkdocs.exe

Anschließend kann man sich die Dokumentation unter localhost:8000 ansehen. Der Webserver kann durch drücken von Strg+C beendet werden.

Auf Github-Pages deployen

Github-Pages ist für jedes Repository auf Github verfügbar. Um eine MkDocs-Seite über Github-Pages verfügbar zu machen, muss man zuerst den Subbefehl gh-deploy von MkDocs ausführen:

mkdocs gh-deploy

~/AppData/Roaming/Python/Python310/Scripts/mkdocs.exe gh-deploy

Anschließend sollte Github automatisch ein Github-Pages Environment hinzufügen, welches die Seite unter https://<username>.github.io/<repositoryName> verfügbar machen.

Optional: Einrichten einer CI-Pipeline

Durch das einrichten einer CI-Pipeline kann man das aufrufen von mkdocs gh-deploy automatisieren. Dazu muss man folgenden Inhalt in die Datei .github/workflows/ci.yml im Projektverzeichnis schreiben:

name: ci 
on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: 3.x
      - run: pip install mkdocs-material 
      - run: mkdocs gh-deploy --force