Logo

Nextcloud-Dokumentation

Generierung zusätzlicher Dokumentation für die Forschungsdatenmanagement- / Kollaborationssoftware Nextcloud als statische HTML-Seiten unter Anwendung vordefinierter Dokumentationsvorlagen. Die Eingabe ist einfaches Markdown und der Generierungsprozess verwendet das MkDocs-Modul in GitLab. Dieses Projekt ist eine typische Darstellung einer auf CI/CD-Pipelines basierenden Generierung statischer HTML-Seiten, die in Bereichen eingesetzt wird, die aus Entwickler*innen, technischen Redakteur*innen oder zur Generierung zusätzlicher Dokumentation für Forschungsdaten bestehen.

Idea
Plan
Prototype
Pilot
Live

Übersicht

Mehrwert: Generierung zusätzlicher Dokumentation für die Forschungsdatenmanagement- / Kollaborationssoftware Nextcloud als statische HTML-Seiten unter Anwendung vordefinierter Dokumentationsvorlagen. Die Eingabe ist einfaches Markdown und der Generierungsprozess verwendet das MkDocs-Modul in GitLab. Dieses Projekt ist eine typische Darstellung einer auf CI/CD-Pipelines basierenden Generierung statischer HTML-Seiten, die in Bereichen eingesetzt wird, die aus Entwickler*innen, technischen Redakteur*innen oder zur Generierung zusätzlicher Dokumentation für Forschungsdaten bestehen.

Problem: Ohne automatisierte HTML-Generierung aus Markdown kann Dokumentation nicht zuverlässig standardisiert oder über Teams hinweg gewartet werden. Es besteht Bedarf an einem konsistenten, leicht aktualisierbaren Dokumentationssystem für Nextcloud, da manuelle Aktualisierungen fehleranfällig sind.

Lösung: Generierung zusätzlicher Dokumentation für die Forschungsdatenmanagement- / Kollaborationssoftware Nextcloud als statische HTML-Seiten unter Anwendung vordefinierter Dokumentationsvorlagen.

Wer profitiert

Primär

  • Betreiber*innen der lokalen Nextcloud-Instanzen

Sekundär

  • Nutzer*innen der spezifischen Nextcloud-Instanz

Wann geeignet

  • Bei der Wartung oder Aktualisierung technischer Nextcloud-Dokumentation.
  • Wenn automatisierte statische HTML-Generierung via CI/CD benötigt wird.

Wann nicht geeignet

  • Wenn keine GitLab- oder CI/CD-Infrastruktur verfügbar ist.
  • Wenn dynamische Echtzeit-Dokumentation anstelle von statischem HTML erforderlich ist.

Prozess

  1. Markdown-Dokumentation wird in GitLab verfasst und versionskontrolliert.
  2. Automatisierte CI/CD-Pipeline unter Verwendung von GitLab und Docker.
  3. Statische HTML-Generierung mit MkDocs-Vorlagen.
  4. Überprüfung und Bereitstellung der generierten Dokumentation.
  5. Kontinuierliche Wartung abgestimmt auf Nextcloud-Updates.

Voraussetzungen

Personen

  • Nextcloud-Betreiber*innen
  • GitLab-Administrator*innen

Daten-Inputs

  • Markdown-Dokumentationsdateien
  • MkDocs-Konfiguration

Tools & Systeme

  • GitLab CI/CD
  • Docker
  • MkDocs

Richtlinien & Compliance

  • Zugriffskontrollrichtlinie der Universität
  • Standards für Dokumentations-Versionskontrolle

Risiken & Gegenmaßnahmen

  • Build-Fehler oder fehlerhaftes HTML aufgrund falscher Markdown-Syntax.

    • Verwendung der CI/CD-Pipeline zur automatischen Syntaxprüfung und Testausführung.

  • Unbefugter Zugriff oder Änderungen an der Dokumentation.

    • Durchsetzung von GitLab-Zugriffskontrollen und SSO-Authentifizierung.

Erste Schritte

Voraussetzungen: Git-Zugriff und konfigurierte Tools/Systeme wie unten aufgeführt.

  1. Repository/Vorlage/Inhalt nach Bedarf vorbereiten
  2. Tools, Berechtigungen und Integrationen konfigurieren
  3. Workflow ausführen und Ergebnisse überprüfen

Ressourcen

FAQ

Wie wird Dokumentation automatisch generiert?

Markdown-Dateien werden in GitLab versionskontrolliert und über eine CI/CD-Pipeline mit MkDocs verarbeitet, um statische HTML-Seiten zu erstellen.

Können mehrere Betreuer*innen sicher zusammenarbeiten?

Ja, GitLab-Zugriffskontrollen und Versionierung verhindern Konflikte und unbefugte Änderungen.

Wie werden Build-Fehler behandelt?

Die CI/CD-Pipeline prüft die Syntax und meldet Fehler vor der Bereitstellung.

Kann die Dokumentation kontinuierlich bereitgestellt werden?

Ja, die Pipeline kann die HTML-Dokumentation automatisch aktualisieren, wann immer Änderungen gemerged werden.

Glossar

MkDocs
Generator für statische Seiten, der Markdown-Dateien in HTML-Dokumentationsseiten umwandelt.
CI/CD-Pipeline
Automatisierter Workflow in GitLab zum Erstellen, Testen und Bereitstellen von Artefakten wie Dokumentation.
Docker
Container-Plattform, die verwendet wird, um die Build-Umgebung für MkDocs zu isolieren.
Markdown
Leichtgewichtige Auszeichnungssprache, die zum Verfassen des Dokumentationsinhalts verwendet wird.