Dokumentation in GitLab CI/CD-Pipelines erstellen

In diesem Modul geht es darum, wie Sie mit MkDocs Dokumentation für Ihr Projekt erstellen und bereitstellen. MkDocs ist ein leistungsfähiges Werkzeug zum Erzeugen statischer Websites aus Markdown-Dateien und lässt sich nahtlos mit GitLab Pages verbinden. Am Ende dieses Moduls können Sie MkDocs einrichten, Dokumentation verfassen und sie über GitLab CI/CD bereitstellen.

Lernziele

MkDocs und seine Konfiguration verstehen.

• Ein MkDocs-Projekt einrichten.
• Dokumentation mit Markdown schreiben und strukturieren.
• Dokumentation lokal bauen und in der Vorschau anzeigen.
• GitLab CI/CD so konfigurieren, dass die Dokumentation über GitLab Pages bereitgestellt wird.

1. Einführung in MkDocs

MkDocs ist ein Generator für statische Websites, der Markdown für die Erstellung der Inhalte und YAML für die Konfiguration verwendet. Er bietet eine einfach zu bedienende Oberfläche zum Erzeugen von Projektdokumentation.

Wichtige Funktionen:

• Markdown-Unterstützung: Verfassen Sie Dokumentation in Markdown.
• Anpassbare Themes: Wählen Sie aus integrierten Themes oder gestalten Sie ein eigenes.
• GitLab-Pages-Integration: Stellen Sie Dokumentation ganz einfach über GitLab Pages bereit.

Praktische Übung

1. MkDocs installieren:

   • Installieren Sie MkDocs lokal auf Ihrem Rechner. Das ist mit pip möglich:

     pip install mkdocs
     

2. Neues MkDocs-Projekt erstellen:

   • Führen Sie den folgenden Befehl in Ihrem Terminal aus, um ein neues MkDocs-Projekt zu erstellen:

     mkdocs new my-project-docs
     cd my-project-docs
     

3. Dokumentation strukturieren:

   • Sehen Sie sich die erzeugte Projektstruktur an. Suchen Sie die Konfigurationsdatei mkdocs.yml und das Verzeichnis docs/.

4. Entwicklungsserver starten:

   • Starten Sie den MkDocs-Entwicklungsserver, um eine Vorschau Ihrer Dokumentation anzuzeigen:

     mkdocs serve
     

   • Öffnen Sie Ihren Browser und rufen Sie http://127.0.0.1:8000 auf, um die Standarddokumentation zu sehen.