In diesem Artikel werde ich Sie Schritt für Schritt anleiten, um eine dynamische Dokumentationsseite zu erstellen, die an jedes Projekt angepasst werden kann und auf der Sie Ihre Dokumentation mit einer Datenbank verbinden können, um Daten zu extrahieren und anzuzeigen und so die Informationen sicherzustellen ist immer auf dem neuesten Stand. Wir werden auch untersuchen, wie wir den gesamten Prozess automatisieren können, von der Inhaltserstellung bis zur Bereitstellung in der Cloud mit AWS.

Die Lösung umfasst Unterstützung für Diagramme und Diagramme, kontinuierliche Integration (CI/CD) mithilfe eines einfachen Workflows in GitHub Actions und automatische Bereitstellung mithilfe von Terraform. Fangen wir an!

Was ist Dokumentation als Code?

Dokumentation und ihre Aktualisierungen sind in vielen Unternehmen, die Software entwickeln, ein wichtiger Prozess, der häufig mit verschiedenen Tools durchgeführt wird, von denen viele kostenpflichtige Lösungen sind.

Daher ist in jüngster Zeit das Konzept von „doc as code“ entstanden. Dies bedeutet, dass für die Verwaltung, Versionierung und Bereitstellung der Dokumentation dieselben Tools und Arbeitsabläufe wie in der Softwareentwicklung verwendet werden müssen.

Dieser Ansatz ermöglicht nicht nur eine bessere Nachverfolgung der Dokumentation, sondern erleichtert auch deren Pflege und stellt die Übereinstimmung mit denselben Best Practices sicher, die in der Softwareentwicklung verwendet werden, nicht nur im Code, sondern auch in der Dokumentation.

Werkzeuge zur Dokumentation als Code

Für die Entwicklung dieser Websites ist es wichtig, einige Praktiken und Tools zu verstehen, die es uns ermöglichen, diesen Ansatz umzusetzen. Nachfolgend finden Sie eine detaillierte Liste der wichtigsten Aspekte, die in diesem Tutorial behandelt werden sollen.

• ? Markdown: Aufgrund ihrer Einfachheit und Integration mit Versionskontrollplattformen und statischen Site-Generatoren die gebräuchlichste Auszeichnungssprache zum Schreiben von Dokumentation.
• ?️ Git: Git ermöglicht die Versionierung von Dokumentation genau wie Code. Dank Git wird jede Änderung in der Dokumentation aufgezeichnet, sodass Teams Änderungen verfolgen, Änderungen rückgängig machen und effizienter zusammenarbeiten können.
• ? Gitflow: Diese Methodik bietet einen strukturierten Workflow zur Verwaltung von Versionen und Revisionen der Dokumentation und stellt sicher, dass Änderungen genehmigt und getestet werden, bevor sie in die Produktion gelangen. Gitflow erleichtert auch die Zusammenarbeit zwischen Teams und ermöglicht so ein sicheres und organisiertes Änderungsmanagement.
• ☁️ Cloud-Dienste: Mithilfe von Diensten wie AWS S3, Netlify oder GitHub Pages können Sie Dokumentation zu geringen Kosten bereitstellen. Diese Dienste ermöglichen die Erstellung schneller, sicherer und leicht zugänglicher statischer Websites.
• ? Statische Site-Generatoren: Tools wie Docusaurus, Jekyll oder Hugo konvertieren Markdown-Dokumentation in eine navigierbare Website, sodass Sie ohne Server umfangreiche und organisierte Dokumentation erstellen können.
• ? Kontinuierliche Integration (CI/CD): CI/CD-Pipelines (z. B. GitHub Actions, GitLab CI oder Jenkins) ermöglichen Ihnen die automatische Bereitstellung von Dokumentation, wenn eine neue Version zusammengeführt oder Änderungen genehmigt werden. Dadurch ist sichergestellt, dass die Dokumentation immer auf dem neuesten Stand ist.

Vorteile von Docs-as-Code

• ✅ Konsistenz und Qualität: Durch den Einsatz von Versionskontrolle und Änderungsprüfungen bleibt die Dokumentation konsistent und von hoher Qualität.
• ⚙️ Automatisierung: CI/CD-Tools ermöglichen die Automatisierung der Dokumentationsbereitstellung, reduzieren Aktualisierungszeiten und minimieren Fehler.
• ? Effiziente Zusammenarbeit: Mit Tools wie Git können Teams bei der Erstellung und Pflege von Dokumentationen ohne Konflikte zusammenarbeiten.
• ? Vereinfachte Wartung: Die Pflege der Dokumentation ist in den Entwicklungsworkflow integriert, sodass Aktualisierungen einfacher werden, wenn sich der Code weiterentwickelt.

? MkDocs

MkDocs ist ein in ?Python geschriebener statischer Site-Generator, der speziell für die Dokumentation von Projekten entwickelt wurde. Ziel ist es, die Erstellung von Dokumentationen mithilfe von Markdown-Dateien zu vereinfachen, die einfach zu schreiben und zu lesen sind.

Mit minimaler Konfiguration konvertiert MkDocs Markdown-Dateien in eine navigierbare und gut strukturierte Dokumentationswebsite und ist damit ideal für Entwickler und Teams, die ihre Dokumentation auf dem neuesten Stand halten möchten.

✏️ MkDocs-Material

MkDocs Material ist ein erweitertes Theme für MkDocs, das den Materialdesign-Richtlinien von Google folgt.

? Zu den Hauptmerkmalen gehören:

• ? Responsive Design: Passt sich automatisch an jede Bildschirmgröße an.
• ? Anpassung: Ändern Sie ganz einfach Farben, Schriftarten, Favicon und Logo, um sie an die visuelle Identität Ihres Projekts anzupassen.
• ? Suchoberfläche: Die erweiterte Suche gruppiert Ergebnisse und hebt gesuchte Begriffe hervor, damit Benutzer die benötigten Informationen finden können.
• ⚡ Lazy Loading: Implementiert Lazy Loading für Suchergebnisse, verbessert die Leistung und verkürzt die Ladezeiten.
• ? Integrationen: Kompatibel mit Google Analytics, Disqus und GitHub, erleichtert Verkehrsanalyse, Benutzerfeedback und direkte Verbindung zum Projekt-Repository.

✏️ Meerjungfrau

Mermaid ist eine JavaScript-Bibliothek zum Erstellen von Diagrammen und Diagrammen aus Text. Durch die Integration mit MkDocs Material können Sie mit Mermaid Visualisierungen wie Flussdiagramme, Entitätsbeziehungsdiagramme und andere Diagramme innerhalb der Dokumentation ohne externe Tools erstellen.

? Dynamische Seite: Jinja

Jinja ist eine Bibliothek, die das Einbetten von Variablen und Daten aus Python-Wörterbüchern in HTML ermöglicht und so Webseiten dynamisch macht. Diese Bibliothek wird häufig zum Generieren von dynamischem HTML und zum Versenden personalisierter E-Mails verwendet.

? Docusaurus-Übersicht

Docusaurus ist ein 2007 von Meta entwickeltes Open-Source-Projekt, das die Erstellung, Bereitstellung und Wartung von Dokumentationswebsites auf schnelle und effiziente Weise vereinfacht. Es ermöglicht die Verwendung von Markdown und MDX zum Schreiben von Inhalten, während sein auf React basierender Kern eine vollständige Anpassung der Stile an die spezifischen Anforderungen des Projekts ermöglicht.

Darüber hinaus unterstützt Docusaurus Mermaid über das Plugin @docusaurus/theme-mermaid und ermöglicht so die Einbindung von Diagrammen und Diagrammen direkt in die Dokumentation.

? Diagramm als Code

Diagramm als Code ist ein Ansatz, der es Ihnen ermöglicht, Diagramme durch Code zu erstellen, anstatt herkömmliche Grafiktools zu verwenden. Anstatt Diagramme manuell zu erstellen, schreiben Sie Code in eine Textdatei, um die Struktur, Komponenten und Verbindungen Ihrer Diagramme zu definieren.

Dieser Code wird dann in grafische Bilder übersetzt, was die Integration und Dokumentation in Softwareprojekten erleichtert. Es ist besonders nützlich für die programmgesteuerte Erstellung und Aktualisierung von Architektur- und Flussdiagrammen.

? Diagramm als Code: Beispiel für die Erstellung von Cloud-Diagrammen

Wie bereits erwähnt, ermöglicht Ihnen Diagramme die Erstellung von Blaupausen unter Verwendung der Symbole der wichtigsten Cloud-Technologien. Die Darstellung dieser Diagramme erfolgt über Knoten. In unserem Beispiel verwenden wir alle Cloud-bezogenen Knoten und AWS-Dienste.

Weitere Informationen dazu, wie ich dies erstellt habe, können Sie in meinem Artikel über Diagramm als Code lesen. Die vollständige Implementierung finden Sie in diesem Repository:

? Anwendungsfall: Erstellen einer Dokumentationsseite für ein maschinelles Lernprojekt

In diesem Anwendungsfall erstelle ich eine Dokumentationsseite für ein Projekt zum maschinellen Lernen mit ? Krankenhausdaten. Ziel ist es, zunächst mit MkDocs eine interaktive Dokumentationsseite zu erstellen und diese später auf Docusaurus zu migrieren. Die Site wird sowohl statische als auch dynamische Komponenten enthalten, um spezifische Anforderungen zu erfüllen, wie z. B. die Einbettung visueller Diagramme und die dynamische Aktualisierung von Daten aus einer SQLite-Datenbank.

? Hauptmerkmale der Dokumentationsseite

1. Visuelle Darstellungen: Ich werde Diagramme einbetten, die mit Diagrammen (Diagramm als Code) erstellt wurden, um die Architektur der Pipeline für maschinelles Lernen effektiv zu veranschaulichen.
2. Dynamische Datenaktualisierungen: Die Dokumentation zeigt die Version und das Datum der letzten Aktualisierung dynamisch an und bezieht diese Informationen aus einer SQLite-Datenbank, um Genauigkeit und Relevanz sicherzustellen.
3. Datenbeispiel: Die Dokumentation enthält ein Beispiel aus der Synthea-Patiententabelle, das synthetische Daten als Beispiel zeigt.

? Seiten der Website

Aus diesem Grund wird unsere Dokumentationsseite die folgenden Seiten haben:

• ? Startseite: Die Homepage der Dokumentation.
• ? Tabellen:Erläuterung der Synthea-Datentabellen und ihrer Verwendung.
• ? Architektur:Ein detaillierter Überblick über die Datenverarbeitungsarchitektur, gehostet auf AWS.
• ? Glossar: Ein Glossar der im gesamten Projekt verwendeten Begriffe

MkDocs-Implementierung

In diesem Abschnitt gehen wir die Schritte zum Einrichten eines Dokumentationsprojekts mit MkDocs von Grund auf durch und erläutern die organisierte Verzeichnisstruktur.

? Voraussetzungen für MkDocs

Um zu beginnen, müssen Sie die folgenden ?Python-Bibliotheken installieren:

MkDocs und das Material installieren

  pip install mkdocs mkdocs-material

Installieren Sie zusätzliche Bibliotheken, um die dynamische Inhaltsaktualisierung zu ermöglichen

  pip install aiosql pandas sqlite3 jinja2 shutil

? Mkdocs: Projekteinrichtung

Initialisieren Sie das Projekt

Beginnen Sie mit der Erstellung eines neuen MkDocs-Projekts. Führen Sie die folgenden Befehle in Ihrem Terminal aus:

   mkdocs new mkdocs
   cd mkdocs

Dieser Befehl erstellt ein grundlegendes MkDocs-Projekt mit einer Standardstruktur.

Erkunden Sie die Verzeichnisstruktur

Sobald die MkDocs-Site erstellt wurde, müssen Sie die folgenden Dateien und Ordner hinzufügen, da diese nicht standardmäßig enthalten sind. 
Denken Sie daran, dass die Links zum Repository am Ende dieses Beitrags als Referenz bereitgestellt werden und jede Komponente im Folgenden ausführlich erläutert wird.

  pip install mkdocs mkdocs-material

?Mkdocs: Komponentenübersicht

? Mkdocs: mkdocs.yml konfigurieren

Sobald wir unsere Projektstruktur eingerichtet haben, konfigurieren wir sie Schritt für Schritt, beginnend mit der Datei mkdocs.yml. Diese Datei definiert die Struktur und Einstellungen für Ihre Dokumentationsseite. So sollte es aufgebaut sein:

mkdocs.yml

  pip install mkdocs mkdocs-material

In dieser Konfigurationsdatei können Sie im Abschnitt nav hauptsächlich die Seiten sehen, die über das Menü zugänglich sind. Anschließend spezifizieren wir die Mermaid-Erweiterung, die im nächsten Abschnitt erläutert wird. Schließlich wendet der Abschnitt Thema das Material-Thema an und aktiviert den in dieser Bibliothek verfügbaren Stil und die Komponenten.

✏️ Mkdocs: Mermaid-Erweiterung

Wie bereits erwähnt, ist Mermaid eine JavaScript-Bibliothek zum Erstellen von Diagrammen und Diagrammen aus Text. Nachfolgend sehen wir einige Beispiele. In unserem Fall werden wir es verwenden, um ein Entity-Relationship-Diagramm (ERD) auf der Seite Tabellen der Dokumentation zu generieren.

Im Repository können Sie sehen, wie dieser Code basierend auf dem Entity Relationship Diagram (ERD) erstellt wird, das in der offiziellen Synthea-Dokumentation zu finden ist. Sie können sich auch das Beispiel der Tabellenseite unter folgendem Link ansehen: tables.md.

⚙️ Mkdocs: Dynamische Inhalte mit Jinja

Um die dynamische Inhaltsgenerierung für unsere Dokumentationsseite zu ermöglichen, verwenden wir Jinja, um Vorlagen zu verarbeiten und Platzhalter durch tatsächliche Daten zu ersetzen. Nachfolgend finden Sie eine schrittweise Aufschlüsselung:

1. Einen Vorlagenordner einrichten
   
   Erstellen Sie einen Ordner mit dem Namen „templates“, um alle Markdown-Dateien für die Site zu speichern. Diese Dateien sollten Platzhalter enthalten. Beispielsweise könnten Sie in index.md Platzhalter wie {{database.version_date}} und {{database.version}} haben.

2. Platzhalter verwenden
   
   Platzhalter sind dynamische Variablen in den Markdown-Dateien. Diese Variablen werden automatisch mithilfe von Python-Wörterbüchern aktualisiert, um relevante Daten einzufügen.

3. Dynamische Inhalte mit update.py generieren

   • Bereiten Sie Ihre Markdown-Vorlagen vor, indem Sie die Abschnitte identifizieren, in denen dynamische Daten erforderlich sind.
   • Verwenden Sie ein Python-Skript (update.py), das in meinem Repository verfügbar ist, um die Vorlagen zu verarbeiten. Das Skript führt die folgenden Aufgaben aus:
     • Datenbankverbindung: Stellt eine Verbindung zu einer SQLite-Datenbank her, um die neuesten Werte abzurufen.
     • Vorlagen-Rendering: Verwendet die Jinja-Bibliothek, um Platzhalter durch Daten aus der Datenbank zu ersetzen.
     • Dateigenerierung: Gibt aktualisierte Markdown-Dateien in den Ordner „docs“ aus, bereit zum Rendern in MkDocs.

  pip install mkdocs mkdocs-material

  pip install aiosql pandas sqlite3 jinja2 shutil

Indem Sie diese Schritte befolgen, können Sie den Aktualisierungsprozess für Ihre Dokumentationsseite automatisieren und so sicherstellen, dass der Inhalt ohne manuelle Bearbeitungen dynamisch und relevant bleibt.

Dynamische Aktualisierung von Datentabellen

Im nächsten Beispiel aktualisieren wir den Inhalt in der Datei tables.md, um ein Beispiel der Tabelle Personen aus der Datenbank anzuzeigen. Dazu erstellen wir einen Platzhalter {{table.person}} innerhalb der Markdown-Datei. Die Idee besteht darin, die Daten dynamisch aus der Tabelle Personen abzurufen und dann die Jinja-Bibliothek zusammen mit Pandas zu verwenden, um die Abfrageergebnisse in ein Markdown-Tabellenformat zu konvertieren.

Hier ist ein Beispiel dafür, wie die Datei tables.md mit dem Platzhalter aussieht:

   mkdocs new mkdocs
   cd mkdocs

Der Prozess ist wie folgt:

1. Datenbank abfragen: Das Skript fragt die Tabelle Personen in der SQLite-Datenbank ab, um relevante Datensätze abzurufen.
2. In Markdown konvertieren: Mit pandas werden die Ergebnisse der Abfrage in ein Markdown-Tabellenformat konvertiert.
3. Platzhalter ersetzen: Der Platzhalter {{table.person}} in der Datei tables.md wird durch die generierte Markdown-Tabelle ersetzt.

   ? docs/
     ├── ? img/
     ├── `architecture.md`
     ├── `glossary.md`
     ├── `index.md`
     ├── `tables.md`
     ├── ? template/
     │   ├── ? db/
     │   │   ├── ? data/
     │   │   │   ├── hospital.db
     │   │   ├── ? queries/
     │   ├── `architecture.md`
     │   ├── `glossary.md`
     │   ├── `index.md`
     │   ├── `tables.md`
     │   └── `update.py`
   ? infraestructure/
   ? github/
     ├── ? workflows/
     │   ├── main.yml
   ? mkdocs.yml

Auf diese Weise spiegelt die Dokumentation immer aktuelle Daten wider und zeigt dynamische Beispiele basierend auf dem tatsächlichen Inhalt der Datenbank an.

⚙️ Mkdocs: Endgültiger Arbeitsablauf

1. Vorlagen erstellen: Entwickeln Sie Ihre Seiten im Verzeichnis docs/template.
2. Führen Sie update.py aus: Füllen Sie dynamische Inhalte aus und generieren Sie die endgültigen Dateien in docs/output.
3. Lokale Vorschau: Verwenden Sie mkdocs Serve, um eine Vorschau der Site auf localhost anzuzeigen.
4. Für die Bereitstellung erstellen: Verwenden Sie mkdocs build, um eine statische Site im Ordner docs/ zu generieren.
5. Bereitstellen: Verwenden Sie Terraform, um die Site in einem AWS S3-Bucket bereitzustellen. Ausführliche Anweisungen finden Sie im Abschnitt „Bereitstellung“ dieses Beitrags.

? Docusaurus-Implementierung

In den folgenden Abschnitten werde ich detaillierte Schritte und Einblicke in die Implementierung einer Dokumentationsseite mit Docusaurus geben. Dazu gehören Einrichtungs-, Anpassungs- und Bereitstellungsoptionen.

? Hauptmerkmale von Docusaurus

• ? Mermaid-Unterstützung: Ähnlich wie MkDocs unterstützt Docusaurus Mermaid beim Einbetten von Diagrammen.
• ⚛️ React-Komponenten: Docusaurus basiert auf React und ermöglicht die Integration dynamischer Komponenten in Ihre Dokumentation.
• ? Dynamischer Inhalt: Nutzt Python-Skripte, um Inhalte dynamisch aus einer SQLite-Datenbank abzurufen und zu aktualisieren.

? Docusaurus-Setup: Von Grund auf neu

Um mit Docusaurus zu beginnen, folgen wir einem schnellen Einrichtungsprozess, der den Schritten, die wir für MkDocs verwendet haben, sehr ähnlich ist, jedoch mit anderen Tools.

1. Erstellen Sie ein neues Docusaurus-Projekt: Installieren Sie zunächst Node.js und führen Sie den folgenden Befehl aus, um eine neue Docusaurus-Site zu erstellen:

  pip install mkdocs mkdocs-material

1. Mermaid-Paket installieren: Um Mermaid-Diagramme zu aktivieren, installieren Sie das erforderliche Paket:

  pip install aiosql pandas sqlite3 jinja2 shutil

1. Führen Sie den Entwicklungsserver aus: Navigieren Sie nach der Installation zu Ihrem Projektverzeichnis und führen Sie den Entwicklungsserver aus:

   mkdocs new mkdocs
   cd mkdocs

1. Besuchen Sie die Website: Ihre Website wird lokal unter http://localhost:3000 verfügbar sein.

? Docusaurus-Anpassung: Konfiguration

In der Konfigurationsdatei docusaurus.config.js passen wir den Titel, das Thema und die Navigation an und aktivieren Funktionen wie Mermaid für die Diagrammdarstellung.
Beispiel-Snippet zum Aktivieren von Mermaid:

  pip install mkdocs mkdocs-material

? Docusaurus Anpassen der Homepage

Um die Homepage anzupassen, ändern wir die Datei src/components/HomepageFeatures/index.js. Hier können Sie das Objekt FeatureList anpassen, um die auf der Startseite angezeigten Funktionen zu aktualisieren.

? Organisation und Struktur des Docusaurus-Inhalts

Genau wie in MkDocs unterstützt Docusaurus Markdown-Dateien für Inhalte, und wir organisieren die Struktur wie folgt:

1. Vorlagenordner: Speichern Sie Ihre Markdown-Dateien im Verzeichnis docs/template und erstellen Sie ein Python-Skript (ähnlich update.py), um dynamische Daten abzurufen und in diese Vorlagen einzufügen.
2. Kategoriedatei (__category__.json): Um die Reihenfolge der Dokumente in der Seitenleiste zu verwalten, erstellen Sie in jedem Ordner eine __category__.json-Datei. Zum Beispiel:

  pip install aiosql pandas sqlite3 jinja2 shutil

__category__.json Beispiel:

   mkdocs new mkdocs
   cd mkdocs

⚙️ Dynamische Daten mit Jinja

Um dynamische Inhalte wie Datenbanktabellen einzubinden, verwenden wir ein ?Python-Skript namens update.py, das Sie im Repository finden.

Dieses Skript ruft Daten aus einer SQLite-Datenbank ab und verarbeitet die im Vorlagenordner gespeicherten Markdown-Dateien. Anschließend aktualisiert es diese Dateien mit den abgerufenen Daten und kopiert sie in den Ordner „docs“, um sie für das Rendern auf der Website vorzubereiten.

Dieser Workflow stellt sicher, dass der Inhalt aktuell und bereit für die Bereitstellung bleibt, und folgt dabei einem ähnlichen Ansatz wie dem, den wir mit MkDocs implementiert haben.

⚙️ Docusaurus: Endgültiger Arbeitsablauf

1. Vorlagen erstellen: Entwickeln Sie Ihre Markdown-Dateien im Verzeichnis docs/template.
2. Python-Skript ausführen: Verwenden Sie das Skript, um Daten dynamisch in die Vorlagen einzufügen.
3. Lokale Vorschau: Führen Sie npx docusaurus start aus, um eine Vorschau der Website anzuzeigen.
4. Für die Bereitstellung erstellen: Sobald Sie fertig sind, verwenden Sie npx docusaurus build, um die statische Site zu generieren.
5. Bereitstellen: Hosten Sie die statischen Dateien auf Ihrer bevorzugten Plattform, z. B. AWS S3.

? Einsatz

In diesem Abschnitt behandeln wir den Bereitstellungsprozess für MkDocs und Docusaurus unter Verwendung von AWS S3 zum Hosten. Während die Bereitstellungsschritte für beide Tools gleich sind, unterscheiden sich die Installationsprozesse, wobei MkDocs Python-basiert und Docusaurus JavaScript-basiert ist.

Infrastrukturaufbau mit Terraform

Um eine statische Dokumentationsseite für AWS S3 bereitzustellen, verwenden wir Terraform, um die erforderlichen Ressourcen bereitzustellen und zu konfigurieren. Das Setup definiert den S3-Bucket, ermöglicht statisches Website-Hosting und konfiguriert den öffentlichen Zugriff mit einer Bucket-Richtlinie, um schreibgeschützten Zugriff zu ermöglichen. Sie finden die Datei main.tf im Repository.

? Schlüsselkomponenten für die S3-Bereitstellung

1. S3-Bucket-Erstellung: Die Ressource zum Erstellen des S3-Buckets, in dem die Dokumentation gehostet wird.
2. Statisches Website-Hosting: Konfiguration für statisches Webhosting, wobei index.html und error.html als Haupt- und Fehlerdokumente festgelegt werden.
3. Konfiguration des öffentlichen Zugriffs: Verwaltet den öffentlichen Zugriff auf den S3-Bucket und stellt sicher, dass er für schreibgeschützten Zugriff konfiguriert ist.
4. Bucket-Richtlinie: Ermöglicht öffentlichen Zugriff zum Abrufen des Dokumentationsinhalts aus dem S3-Bucket.

Sie können auf die vollständige Terraform-Datei und die entsprechenden Konfigurationen für die Bereitstellung der Site im Repository zugreifen:

Terraform-Konfigurationsdatei:

• mkdocs-Datei
• Docusaurus-Datei

GitHub Action Workflow for Automatic Deployment: Eine CI/CD-Pipeline zur Automatisierung des Deployment-Prozesses ist ebenfalls im Repository enthalten.

• mkdocs-Datei
• Docusaurus-Datei

GitHub-Aktionskonfiguration
Stellen Sie sicher, dass Sie Ihre AWS-Anmeldeinformationen in den GitHub-Repository-Geheimnissen unter Einstellungen > konfigurieren. Geheimnisse > Aktionen. Dadurch kann GitHub Actions sicher auf Ihr AWS-Konto zugreifen und Aktionen wie das Hochladen von Dateien in S3 ausführen, wenn Sie Änderungen an den Hauptzweig übertragen.

Repositories

Unten finden Sie die Links zum gesamten Code zum Bereitstellen Ihrer Dokumentationsseite. Wenn Sie es nützlich finden, können Sie einen Stern hinterlassen ⭐️ und mir folgen, um Benachrichtigungen über neue Artikel zu erhalten. Dies wird mir helfen, in der Tech-Community zu wachsen und mehr Inhalte zu erstellen.

• MkDocs-Bereitstellung: GitHub-Repository für MkDocs

• Docusaurus-Bereitstellung: GitHub-Repository für Docusaurus

? Abschließende Schlussfolgerungen: MkDocs vs. Docusaurus

Beide Lösungen sind einfach zu implementieren, aber in den folgenden Punkten können wir einige Unterschiede untersuchen. Welche die beste Lösung ist, hängt vom Kontext, dem Wissen und der Komplexität ab, die Sie möglicherweise für die Implementierung benötigen.

• ? Sprache & Anpassung: MkDocs basiert auf Python und verfügt über einfache YAML-Konfigurationen und -Vorlagen, ideal für schnelle Einrichtung. Andererseits ist Docusaurus React-basiert und bietet erweiterte Anpassungs- und interaktive Komponenten, wodurch es besser für Benutzer geeignet ist, die mehr Kontrolle über visuelle Elemente benötigen.
• ? Markdown & Rendering: Beide verwenden Markdown, aber Docusaurus ermöglicht interaktive Elemente und eignet sich daher besser für dynamische Inhalte.
• ⚙️ Komplexität: Docusaurus eignet sich besser für komplexe Dokumentationsanwendungen, beispielsweise solche mit Anmeldesystemen. MkDocs ist einfacher, aber Docusaurus bietet mehr Flexibilität für Styling und Funktionen.
• ? Community: Docusaurus verfügt über eine starke Community mit Discord und 74 Plugins, während MkDocs für die Community-Unterstützung auf GitHub-Diskussionen angewiesen ist.
• ☁️ Amazon-Bereitstellung: Sie können eine statische Site auf S3 bereitstellen, um die Bereitstellungskosten zu senken, und auch CI/CD für die automatische Bereitstellung verwenden.

? Referenzen

1. Mkdocs: https://www.mkdocs.org/
2. Mkdocs-Material: https://squidfunk.github.io/mkdocs-material/
3. Diagramme: https://diagrams.mingrammer.com/
4. Docusaurus: https://docusaurus.io/
5. Jinja: https://jinja.palletsprojects.com/en/stable/
6. Git Book – Was ist doc as code: https://www.gitbook.com/blog/what-is-docs-as-code
7. Schreiben Sie die Dokumente: https://www.writethedocs.org/guide/docs-as-code/

Das obige ist der detaillierte Inhalt vonBereitstellen von Docs-as-Code auf AWS: Erstellen dynamischer Dokumentationsseiten in MkDocs und Docusaurus. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!