Docs-as-Code in Aktion: Dokumentieren einer Python-Bibliothek.

Dokumentation ist eine entscheidende Ressource, um Ihrer Zielgruppe zu helfen, zu verstehen, wie sie Ihr Produkt effektiv nutzt. Eine hochwertige Dokumentation kommuniziert nicht nur das Kernproblem, das Ihr Produkt löst, sondern ermöglicht es Benutzern auch, die gewünschten Ergebnisse nahtlos zu erzielen.

Das Gleiche gilt für Open-Source-Bibliotheken und -Pakete. Eine klare und zugängliche Dokumentation ist unerlässlich, um Entwicklern bei der erfolgreichen Integration dieser Tools in ihre Projekte zu helfen.

In den letzten Jahren hat der Docs-as-Code (DaC)-Ansatz zur Dokumentation erheblich an Popularität gewonnen. Bei dieser Methode wird die Dokumentation als grundlegender Bestandteil des Softwareentwicklungslebenszyklus behandelt, indem dieselben Tools und Prozesse verwendet werden, auf die sich Entwickler für Code verlassen.

Diese Methode ist weithin akzeptiert, da sie eine konsistente, versionierte und leicht zu wartende Dokumentation fördert, die sich parallel zum Produkt weiterentwickelt.

Was ist Docs-as-Code?

Einfach ausgedrückt ist DaC eine Methode, die die Handhabung und Pflege der Dokumentation umfasst, wie Sie es auch mit Ihrem Code tun würden.

Ein typischer Softwareentwicklungslebenszyklus umfasst 7 Phasen, darunter Folgendes:

1. Planung
2. Anforderungen sammeln und analysieren
3. Design
4. Codierung und Implementierung
5. Codetests
6. Codebereitstellung
7. Codepflege

Deshalb ist DaC ein neuer Ansatz, der sicherstellt, dass die Dokumentation dieselben Phasen durchläuft. Dadurch bleibt die Dokumentation versioniert und bei Softwareänderungen auf dem neuesten Stand.

Bereitstellung ohne DaC

Bereitstellung mit DaC

Auch wenn dieser Leitfaden möglicherweise nicht ausführlich auf den theoretischen Aspekt von DaC eingeht, können Sie den Artikel „Anfängerleitfaden für Docs-as-Code“ lesen, der das Konzept hinter DaC im Detail erklärt.

Projektübersicht

Dieser Leitfaden befasst sich mit der praktischen Implementierung von DaC mit Python. Sie erfahren, wie Sie eine Open-Source-Python-Bibliothek mit Mintlify dokumentieren.

Mintlify ist ein statischer Site-Generator und eine Dokumentationssite, die für die öffentliche Dokumentation verwendet wird. Es ist einfach zu warten und für verschiedene Dokumentationsanforderungen wie Entwicklerdokumentation, API-Dokumentation usw. zu verwenden. Es funktioniert auch gut mit der DaC-Methodik.

Dieses Tutorial ist eine Fortsetzung eines bestehenden Tutorials zum Erstellen und Bereitstellen einer Python-Bibliothek. Mithilfe der DaC-Methodik erfahren Sie, wie Sie das von der Python-Bibliothek entwickelte referenzierte Tutorial dokumentieren.

Es wird empfohlen, dass Sie das vorherige Tutorial abschließen, bevor Sie fortfahren. Sie können jedoch fortfahren, wenn Sie ein bestehendes Projekt haben, das Sie für dieses Tutorial verwenden möchten.

Projektanforderungen

Grundkenntnisse von Git und GitHub, wie man ein Github-Repository erstellt und wie man seinen Code an GitHub überträgt, sind erforderlich. Für dieses Tutorial benötigen Sie außerdem folgende Tools:

• Mintlify-Konto: Sie benötigen ein aktives Mintlify-Konto, um Dokumentation zu erstellen (Schritte finden Sie in der Anleitung).
• Node.js: Sie benötigen Node.js Version 18 und höher, um Mintlify zu installieren und Ihre Dokumentation lokal zu bearbeiten.

Richten Sie eine Mintlify-Dokumentation ein

Befolgen Sie die folgenden Schritte, um eine Dokumentation mit Mintlify einzurichten:

1. Erstellen Sie ein Konto auf Mintlify

2. Richten Sie Ihr Mintlify-Konto ein:
Ein Bestätigungslink wird an Ihre E-Mail gesendet. Dieser Link leitet Sie zur folgenden Seite weiter:

3. Melden Sie sich mit Github an:
Im ersten Schritt müssen Sie sich mit Ihrem Github-Konto anmelden.

4. Erstellen Sie ein GitHub-Repository (Repo) für Ihre Dokumentation:
Im nächsten Schritt müssen Sie die Mintlify-App auf Ihrem Github-Konto installieren und autorisieren. Dadurch kann Mintlify automatisch ein Repo für Ihre Dokumente erstellen

5. Greifen Sie auf Ihr Dokumentations-Repo zu:
Im vorherigen Schritt wird ein neues Dokumenten-Repository für Ihre Dokumentation erstellt. Suchen Sie in Ihren GitHub-Repositorys nach einem neuen Dokumenten-Repository

Fügen Sie die Dokumentation Ihrem Projekt hinzu

Der nächste Schritt besteht darin, das Dokumenten-Repository in Ihre lokale Umgebung zu klonen und es einem vorhandenen Projekt wie einem Entwicklertool, einem Open-Source-Paket usw. hinzuzufügen. Wenn Sie das vorherige Tutorial bereits abgeschlossen haben, wird Ihr Projekt ExchangeLibrary sein.

Folgen Sie den folgenden Schritten, um die Dokumentation zu Ihrem Projekt hinzuzufügen:

1. Öffnen Sie das Terminal und klonen Sie das Dokumenten-Repository mit dem folgenden Befehl:

git clone https://github.com/<your github username>/docs 

2. Kopieren Sie den geklonten Dokumentordner in Ihr Projekt.

3. Öffnen Sie das Projekt in einem Code-Editor.

Ihre Projektdateistruktur sollte nun wie folgt aussehen:

Lokale Vorschau der Dokumentation

Mit Mintlify können Sie Ihre Dokumentation lokal in der Vorschau anzeigen, bevor Sie sie veröffentlichen. Befolgen Sie die folgenden Schritte, um es einzurichten:
1. Öffnen Sie Ihr Projekt im Terminal
2. Führen Sie den folgenden Befehl aus, um Mintlify global zu installieren:

git clone https://github.com/<your github username>/docs 

3. Wechseln Sie zum Ordner „docs“ in Ihrem Projekt:

npm i -g mintlify

4. Starten Sie einen Mintlify-Server mit dem folgenden Befehl:

cd docs

In Ihrem Terminal sollte eine Meldung wie die folgende angezeigt werden:

Öffnen Sie die URL, um eine lokale Vorschau der Dokumentation anzuzeigen. Der Inhalt Ihrer Dokumentation ist die Mintlify-Startdokumentvorlage. Dies ändert sich, wenn Sie mit der Bearbeitung Ihrer Dokumentation beginnen.

Schreiben der Dokumentation

Eine Mintlify-Dokumentation basiert auf der Datei mint.json. Diese Datei enthält das Farbschema, die Paginierung und die Navigationseinstellungen für die Dokumentation. Sie finden es im Dokumentordner des Projekts.

Außerdem werden Dokumentationsdateien in Mintlify in .mdx geschrieben. Es ähnelt fast Markdown (.md), außer dass es spezielle Tags und Symbole zulässt.

In diesem Abschnitt erfahren Sie, wie Sie Ihre Dokumentationseinstellungen in der Datei mint.json bearbeiten und Texte und spezielle Komponenten zu Ihrer Dokumentation hinzufügen.

Dokumentationseinstellungen bearbeiten

Die Datei mint.json ist ein JSON-Objekt, das aus Farbschemata, Paginierung, Navigationseinstellungen usw. für Ihre Dokumentation besteht. Nachfolgend finden Sie eine Liste der verfügbaren Einstellungen und deren Bedeutung:

1. Farbgebung und Aussehen:
Dieser Abschnitt wird verwendet, um das Erscheinungsbild Ihrer Dokumentation zu verschönern und zu verbessern. Es wird verwendet, um das Logo (sowohl für den Hell- als auch für den Dunkelmodus), das Favicon, den Titel und das Farbschema für die Dokumentation zu ändern. Es beginnt beim $schema-Schlüssel bis zum Farbschlüssel, wie unten gezeigt:

mintlify dev

2. Navigationslinks und CTA-Button:
Dieser Abschnitt wird zum Einrichten von Navigationslinks und Schaltflächen oben auf der Dokumentationsseite verwendet. Unten finden Sie ein Beispiel für einen Navigationslink und eine Schaltfläche:

Der folgende Code richtet die Navigationslinks und eine CTA-Schaltfläche für Ihre Mintlify-Dokumentation ein:

  "$schema": "https://mintlify.com/schema.json",
  "name": "<your-documentation-title>",
  "logo": {
    "dark": "<logo-for-dark-mode>",
    "light": "<logo-for-light-mode>"
  },
  "favicon": "<link-to-a-favicon>",
  "colors": {
    "primary": "#0D9373",
    "light": "#07C983",
    "dark": "#0D9373",
    "anchors": {
      "from": "#0D9373",
      "to": "#07C983"
    }
  },

3. Tabs und Anker:
Mithilfe von Tabulatoren und Ankern können Sie horizontale bzw. vertikale Abschnitte in Ihrer Dokumentation einrichten. Nachfolgend finden Sie Beispiele für Registerkarten:

Unten ist ein Beispiel für einen Anker:

Die Einstellungen für diese Komponenten werden über die Tabulator- und Ankertasten verwaltet.

4. Navigationseinstellungen:
Dieser Abschnitt hilft Ihnen, die Seiten in Ihrer Dokumentation zu gruppieren. Es handelt sich um ein Array, das aus einem Gruppenschlüssel und einem Seitenarray besteht, in dem die Seiten für die Gruppe nacheinander hinzugefügt werden. Unten finden Sie ein Beispiel dafür, wie es hinzugefügt wird:

git clone https://github.com/<your github username>/docs 

Die obigen Einstellungen werden in das Bild unten übersetzt:

Die Seiten (Einleitung usw.) sind .mdx-Dateien im Dokumentordner Ihres Projekts.

5. Verschachtelte Navigation:
Die verschachtelte Navigation wird üblicherweise zum Erstellen von Unterabschnitten innerhalb einer Dokumentation verwendet. Unten sehen Sie ein Beispiel für eine verschachtelte Navigation:

Unten finden Sie einen Beispielcode zum Einrichten einer verschachtelten Navigation auf Mintlify:

npm i -g mintlify

Der obige Code verschachtelt einen Abschnitt/eine Gruppe in einem anderen Abschnitt. Der Symbolschlüssel verschönert den Abschnittstitel mit einem Symbol, wenn er auf einer Webseite gerendert wird.

6. Fußzeileneinstellungen:
Der FooterSocials-Schlüssel wird zum Hinzufügen von Social-Media-Konten im Zusammenhang mit der Dokumentation verwendet. Unten ist ein Beispiel:

So fügen Sie Inhalte hinzu

Die Mintlify-Dokumentation führt Sie durch das Hinzufügen von Inhalten zu Ihrer Dokumentation. Ich empfehle Ihnen, sich die Dokumentation anzusehen, um zu erfahren, wie Sie Ihrer Dokumentation verschiedene Inhalte hinzufügen können.

Schauen Sie sich diese Beispieldokumentation an, um sich für die Strukturierung Ihrer eigenen Dokumentation inspirieren zu lassen.

Tipps zum Schreiben von Dokumentationen

Im Folgenden finden Sie einige Tipps, die Ihnen beim Verfassen einer klaren und benutzerfreundlichen Dokumentation helfen:

1. Seien Sie so direkt wie möglich: Vermeiden Sie überflüssige Informationen, die keinen Mehrwert bieten. Ihre Dokumentation richtet sich an Entwickler, die Ihr Paket oder Tool in ihrem nächsten Projekt verwenden möchten. Zeigen Sie ihnen also nur das, was sie dazu benötigen.

2. Fügen Sie eine Beschreibung oder Übersicht Ihres Tools hinzu:
Bevor Sie näher auf die Verwendung Ihres Werkzeugs eingehen, beschreiben Sie kurz, um welches Werkzeug es sich handelt und welches Problem es löst. Dies sollte auf der ersten Seite sein.

3. Fügen Sie genügend Codebeispiele hinzu:
Dies hilft ihnen zu verstehen, wie sie Ihr Werkzeug ohne unnötige Fehler verwenden können. Codebeispiele zur Installation, Authentifizierung, Antwortbeispiele, Methodenargumente usw. sind sehr wichtig.

4. Fehler und Ausnahmen:
Dies hilft Benutzern beim Debuggen. Fügen Sie eine Seite hinzu, um die Art der Fehler zu beschreiben, die bei der Verwendung Ihres Tools auftreten können. Zeigen Sie hierzu auch Codebeispiele an.

Schieben Sie das Projekt auf Github

Folgen Sie den Schritten unten, um das Projekt auf Github zu pushen:

1. Öffnen Sie ein Git-Bash-Terminal in Ihrem Projekt und wechseln Sie mit dem folgenden Befehl in den Ordner „docs“:

git clone https://github.com/<your github username>/docs 

2. Entfernen Sie Git aus diesem Ordner mit dem folgenden Befehl:

npm i -g mintlify

Dieser Befehl entfernt .git aus dem Ordner „docs“, um Probleme zu vermeiden, wenn Sie das gesamte Projekt auf Github übertragen möchten.

3. Schieben Sie das Projekt auf GitHub.

Stellen Sie die Dokumentation bereit

Folgen Sie den folgenden Schritten, um Ihre Dokumentation auf Mintlify bereitzustellen:
1. Melden Sie sich bei Ihrem Mintlify-Dashboard an
2. Klicken Sie auf die Registerkarte „Einstellungen“

3. Ändern Sie Ihr Mintlify Github-Repo in das Repo Ihres Projekts

4. Aktivieren Sie den Monorepo-Schalter. Dies bedeutet, dass der Ordner „docs“ in einem anderen Projekt in einem einzelnen Repo vorhanden ist.

5. Geben Sie **docs als Pfad zur mint.json-Datei in das neue Feld ein, das angezeigt wird.**

6. Klicken Sie auf die Schaltfläche „Speichern“, um die Änderungen zu speichern.

Auf Ihre Dokumentation können Sie über den Link zugreifen, der im Übersichtsreiter Ihres Dashboards angezeigt wird

Aktualisieren des Projekts

Sie werden höchstwahrscheinlich Änderungen an Ihrem Projekt vornehmen und müssen es möglicherweise erneut bereitstellen.

Nachdem Sie Aktualisierungen in Ihrem Projekt vorgenommen haben, stellen Sie sicher, dass Sie die Änderungen auf Github übertragen. Mintlify übernimmt automatisch die neuen Änderungen und aktualisiert Ihre Dokumente umgehend.

Abschluss

In diesem Tutorial haben Sie gelernt, wie Sie mithilfe des Docs-as-Code-Ansatzes eine Dokumentation für eine Python-Bibliothek erstellen.

Docs-as-code fördert die Zusammenarbeit und kontinuierliche Integration in einem Projekt. Wenn es um Open Source geht, ermöglicht Docs-as-Code den Menschen eine nahtlose Zusammenarbeit an einem Projekt und gleichzeitig die ordnungsgemäße Dokumentation auf dem neuesten Stand.

Es gibt verschiedene REST-APIs ohne SDKs oder Programmierbibliotheken. Wählen Sie eines aus, das Sie interessiert, und erstellen Sie etwas Ähnliches.

Weiterbauen ?‍?!

FAQs

Wie kann ich meine Dokumentation testen?

Diese Funktion wird häufig bei großen Projekten mit mehreren Mitwirkenden verwendet. Dokumentationstests werden automatisch ausgeführt, wenn eine Pull-Anfrage an das Projekt gestellt wird. Wenn der Test erfolgreich ist, werden die Änderungen zusammengeführt. Lesen Sie diesen Leitfaden darüber, wie swimm automatische Dokumentationstests anbietet, um mehr zu erfahren.

Kann ich dieses Projekt in anderen Programmiersprachen replizieren?
Ja, das kannst du. Befolgen Sie die Verfahren in dieser Anleitung, um ein ähnliches Ergebnis in Ihrer bevorzugten Sprache zu erhalten.

Gibt es außer Mintlify noch andere Dokumentationsseiten?
Ja, es gibt andere Dokumentationsseiten, die Sie verwenden können. Einige davon umfassen: Gitbook, Readme, Docusaurus usw.

Das obige ist der detaillierte Inhalt vonDocs-as-Code in Aktion: Dokumentieren einer Python-Bibliothek.. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!