Dokumentation

Die Dokumentation der Text+ Registry wird in einem GitLab Repository gepflegt und mit Hilfe von Docusaurus in eine statische Website konvertiert.

Änderungen und Ergänzungen

Wenn Sie an der Erstellung der Dokumentation mitwirken möchten, können Sie Änderungswünsche gerne in Form von Issues im GitLab Repository einstellen. Alternativ können Sie Ergänzungen und Änderungen an den Markdown Dateien gerne auch unmittelbar vornehmen. Es empfiehlt sich die Erstellung von Branches, die dann zunächst in den staging und schließlich in den master Branch der Dokumentation integriert werden. Für Fragen hierzu stehen wir gerne zur Verfügung.

GitLab CI/CD

Master und Staging

Änderungen an der Dokumentation werden für die master und staging Branches mit Hilfe von GitLab CI/CD automatisch in statische Webseiten konvertiert und in Form von GitLab Pages bereitgestellt:

• Im staging Branch sollten zunächst alle Veränderungen an der Dokumentation zusammengeführt werden. Erst nach der Überprüfung der Dokumentation unter https://minfba.de.dariah.eu/registry-docs/staging/ werden Änderungen in den produktiv verteilten master Branch übertragen.
• Für den master Branch wird die Dokumentation unter als GitLab Page unter https://minfba.de.dariah.eu/registry-docs/master/ und https://registry.text-plus.org/docs/ bereitgestellt.

Die Generierung der Websites und die Verteilung an die jeweiligen Stellen kann je nach Verfügbarkeit von GitLab Runnern einige Minuten in Anspruch nehmen. Es empfiehlt sich, den Ablauf der Pipelines im Auge zu behalten, da dort auch bei der Generierung aufgetretene Fehler zu erkennen sind.

Merge Requests

Auch für Merge Requests kann eine Bereitstellung der Dokumentation angestoßen werden bevor diese mit den master und staging Branches zusammengeführt werden. Im Gegensatz zu den master und staging Branches erfolgt diese nur manuell.

Lokales Testen

Docusaurus basiert auf Node.js (Version 18.0 und neuer). Nach der Installation von Node.js können Sie die Dokumentation der Registry auch mit Hilfe von Git abrufen, lokale Änderungen vornehmen und die veränderte Version der Dokumentation bei sich lokal ausführen, bevor Sie geünschte Änderungen in das Git Repository schreiben.

Abrufen mit Hilfe von Git

Mittels SSH

git clone git@gitlab.gwdg.de:textplus/registry/registry-docs.git
cd registry-docs
git switch --create <branch-name>

Mittels HTTPS

git clone https://gitlab.gwdg.de/textplus/registry/registry-docs.git
cd registry-docs
git switch --create <branch-name>

Lokales Ausführen

Im Verzeichnis von registry-docs können Sie mit Hilfe des Kommandos npm start einen lokalen Entwicklungsserver starten und die Auswirkungen Ihren Änderungen testen. Nach Ausführung des Kommandos sollte sich ein Browserfenster http://localhost:3000 öffnen

npm start

Änderungen übermitteln

Änderungen an der Dokumentation können Sie mit den üblichen Git Kommandos in das Repository übertragen.

git add pfad-zum-veränderten-dokument
git commit -m "Änderung beschreiben"
git push --set-upstream origin <branch-name>