Voraussetzungen und Installation¶
Um die Webseite lokal verändern zu können, benötigen Sie eine Grundausstattung an Werkzeugen. Auf dieser Seite listen wir diese ohne ausführliche Installationsanleitungen auf. Wenn einmal der Bedarf aufkommen sollte, werden wir die Gelegenheit nutzen und die Anleitung gemeinsam mit Ihnen ausarbeiten.
Kommandozeile¶
Das Generieren der Webseite sowie die Installation der nötigen Werkzeuge erfolgt weitgehend über die Kommandozeile. Das erfordert aber keine speziellen Vorkenntnisse und sollte Sie nicht von der Mitwirkung abhalten. Auf Mac- und Linux-Rechnern können Sie einfach die vorhandene Terminal-Anwendung verwenden, unter Windows empfehlen wir die PowerShell.
Tools¶
Git¶
Wir arbeiten mit der Versionskontrollsoftware Git. Unter
Linux kann das Paket git aus den Paketquellen installiert werden, Downloads
für Windows und Mac sind über die Homepage erhältlich.
Die Installation und Ersteinrichtung von Git für die verschiedenen Betriebssysteme wird in einem empfehlenswerten Tutorial auf GitHub einfach erläutert. Auf jeden Fall müssen Sie den Namen und die Email-Adresse konfigurieren.
Windows
Für die Windows-Installation können die meisten Vorgaben des Installers beibehalten werden. Wir empfehlen folgende Individualisierungen:
- Komponenten: Die Windows-Explorer-Integration könnte interessant sein.
- Das Festlegen eines Default-Editors ist wichtig! Sonst sehen Sie sich dem Terminal-Editor Vim ausgesetzt. Wählen Sie einen Editor, der bereits installiert ist. Interessant könnte die Option »nano« sein, da dieser innerhalb des Terminals verbleibt, aber viel leichter zugänglich ist als Vim.
- Die Vorgabe zum Verhalten bei "Pull" sollte auf »Rebase« geändert werden.
Python 3¶
Die Werkzeuge sind in der Sprache Python 3 geschrieben, das unter Linux standardmäßig installiert ist, auf MacOS und Windows jedoch separat installiert werden muss (erhältlich über die verlinkte Homepage).
Achtung
Python muss mindestens in der Version 3.7 vorliegen
Windows
Wir empfehlen folgende Einstellungen im Python-Installer:
- Add to PATH
- pip-Installation beibehalten
- Ob Sie Python für alle Benutzer installieren (erfordert Administratoren-Rechte), bleibt Ihnen selbst überlassen.
- Unter Optionen können abgewählt werden:
- Documentation
- tcl/tk and IDLE
- Test suite
- Unter »Advanced Options« belassen Sie bitte die Voreinstellungen
- Nach der Installation ist die Entfernung des Pfad-Limits auf 260 Zeichen sinnvoll, sofern es vom Installer angeboten wirde
pip¶
Alle Tools, die Sie benötigen, um die GLAREAN-Anleitungen zu bearbeiten, können mit pip ganz einfach installiert werden. Je nach Installation und Betriebssystem heißt dieses Tool möglicherweise auch pip3, weshalb Sie ggfs. ein bestimmtes der beiden Kommandos benutzen müssen.
Vermutlich ist der Paketmanager schon (zusammen mit Python selbst) installiert. Das können Sie überprüfen, indem Sie in einem Terminal eines der beiden Kommandos
pip3 --version
pip --version
eingeben. Wenn das Tool vorhanden ist, sehen Sie eine entsprechende Meldung, sonst müssen Sie es noch installieren.
Unter Linux geht das über den Paketmanager Ihrer Distribution, das Paket heißt
i.d.R. python3-pip. Andernfalls laden Sie das Skript
get-pip.py herunter, wechseln in einem
Terminal in das entsprechende Verzeichnis und installieren pip mit
python3 get-pip.py.
Nach einer manuellen Python-Installation kann pip evtl. nicht in der neuesten Version vorliegen, was zu unnötigen Warnmeldungen führt. Aktualisieren Sie das Tool daher bitte vorsorglich mit dem Befehl
python -m pip install --upgrade pip
MkDocs¶
Wir produzieren die GLAREAN-Anleitungen mit MkDocs, einem »Static Site Generator« mit Fokus auf der Erstellung von Dokumentationen. Wir verwenden diesen zusammen mit einigen Plugins und Werkzeugen, insbesondere mkdocs-library, einem speziell für die GLAREAN-Anleitungen entwickelten, inzwischen aber als Freie Software veröffentlichten Tool. Alle verwendeten Abhängigkeiten sind in einem GLAREAN-Plugin definiert, und so können alle benötigten Werkzeuge mit einem einzigen Aufrauf installiert werden. Sicherheitshalber sollten Sie vorab noch ein Hilfsprogramm zu pip installieren. Dies können Sie im Terminal aus einem beliebigen Verzeichnis heraus erledigen.
pip install wheel
pip install git+https://glarean.mh-freiburg.de/git/GLAREAN-Doku/mkdocs-glarean-plugin.git
Projekt-Repository¶
Die Inhalte der Anleitungen werden im Repository https://glarean.mh-freiburg.de/git/GLAREAN-Doku/glarean-books/ auf dem Git-Server der Hochschule verwaltet, das mit
git clone https://glarean.mh-freiburg.de/git/GLAREAN-Doku/glarean-books.git
(Zugriff ausschließlich über HTTPS möglich) in ein beliebiges lokales Verzeichnis geklont werden muss.
Anschließend muss die Seite einmal initialisiert werden, bevor Seiten bearbeitet, hinzugefügt, lokal getestet und anschließend als Pull Request hochgeladen werden können.
cd glarean-books
mkdocs-library
Die erzeugte Seite kann anschließend durch Öffnen der Seite site/index.html in
einem beliebigen Browser betrachtet werden.