DeepDocs: das GitHub-KI-Tool zur automatischen Aktualisierung der Code-Dokumentation

DeepDocs ist ein auf GitHub basierendes KI-Tool, das das Problem der mühsamen Aktualisierung der Codedokumentation lösen soll. Durch die intelligente Analyse von Code-Änderungen aktualisiert es automatisch die Projektdokumentation wie READMEs, API-Referenzen und Tutorials, um sicherzustellen, dass sie mit dem Code synchron bleibt.DeepDocs lässt sich in GitHub-Workflows integrieren, ohne dass eine zusätzliche Plattform erforderlich ist, und ist daher ideal für schnelle Entwicklungsteams. DeepDocs scannt die gesamte Codebasis, identifiziert veraltete Dokumentationen und aktualisiert sie präzise, ohne ihr Format oder ihren Stil zu verändern. Mit einer einfachen Konfiguration können Benutzer die Dokumentenverwaltung automatisieren und so den Bedarf an manueller Pflege reduzieren. DeepDocs legt großen Wert auf den Datenschutz, da der Code zur Laufzeit nur temporär verarbeitet und nicht gespeichert wird.

Funktionsliste

• Laufende Aktualisierung der DokumentationAutomatisches Erkennen und Aktualisieren der betroffenen Dokumente nach jedem Code-Commit.
• TiefenscanVollständige Analyse der Codebasis und Stapelverarbeitung aller veralteten Dokumentationen.
• intelligenter Editor (Software)Aktualisieren Sie nur die notwendigen Teile des Dokuments unter Beibehaltung der ursprünglichen Struktur und des Stils.
• Ausführlicher BerichtErzeugen eines Änderungsberichts, der den Grund für die Aktualisierung der Dokumentation und die damit verbundene Codeübernahme beschreibt.
• Native Integration von GitHubDirekt in GitHub-Workflows einbetten, um separate Zweige für die Übergabe von Dokumentaktualisierungen zu erstellen.
• Unterstützung für mehrere DokumenttypenKompatibel mit READMEs, API-Referenzen, SDK-Anleitungen, Tutorials und mehr.
• DatenschutzDie Verarbeitung des Codes ist vorübergehend und wird nicht gespeichert, wodurch die Datensicherheit gewährleistet ist.

Hilfe verwenden

Einbauverfahren

DeepDocs ist für jedes Entwicklerteam, das GitHub nutzt, sehr einfach zu installieren und zu konfigurieren. Hier sind die detaillierten Installationsschritte:

1. Installation der DeepDocs-GitHub-Anwendung
   Öffnen Sie Ihr GitHub-Repository und gehen Sie zu Settings > GitHub Apps. Den GitHub-Marktplatz durchsuchen DeepDocsAIKlicken Sie auf Configure. Wählen Sie das Code-Repository aus, das überwacht werden soll (wenn sich die Dokumentation in einem separaten Repository befindet, muss sie auch in dieses Repository installiert werden). Klicken Sie auf . Save Speichern Sie die Konfiguration. Wenn Sie weitere Repositories hinzufügen müssen, können Sie dies später in der GitHub Installation Settings Mittlere Einstellung.
2. Erstellen von Konfigurationsdateien
   Erstellen Sie eine Datei im Stammverzeichnis des Code-Repositorys mit dem Namen deepdocs.yml Datei. Im Folgenden finden Sie ein Beispiel für eine Grundkonfiguration:

   target:
   - url: "docs/"
   reinit: "random-string"
   ignore: []
   

   • target: Geben Sie den zu überwachenden Dokumentordner oder Dateipfad an, z. B. docs/.
   • reinitEine zufällige Zeichenkette, mit der ein Tiefenscan manuell ausgelöst werden kann.
   • ignore: Geben Sie Dateien oder Ordner an, die ignoriert werden sollen (optional).
     Übertragen Sie diese Datei in den zu überwachenden Zweig (z. B. main vielleicht dev).
3. Ersten Scan auslösen
   vorlegen (einen Bericht usw.) deepdocs.yml Danach löst DeepDocs automatisch einen Tiefenscan aus, der die gesamte Codebasis analysiert und veraltete Dokumentation aktualisiert. Die Ergebnisse werden in einen neuen Zweig namens deepdocs-deepscan-<branch>-<commit_sha>mit einem aktualisierten Bericht.

Verwendung der Hauptfunktionen

Laufende Aktualisierung der Dokumentation

Die wichtigste Funktion von DeepDocs ist die kontinuierliche Aktualisierung der Dokumentation. Nach jedem Code-Commit (Push- oder Pull-Request) durchsucht DeepDocs den Code automatisch nach Änderungen und bestimmt, welche Dokumentation aktualisiert werden muss. Wenn zum Beispiel ein API-Endpunkt geändert wird, aktualisiert DeepDocs die entsprechende API-Referenzdokumentation. Die Aktualisierungen werden in einen neuen Zweig übertragen (z. B. in den deepdocs-update-<branch>-<commit_sha>), die detaillierte Änderungsberichte enthalten. Benutzer können diese Aktualisierungen direkt auf GitHub überprüfen und zusammenführen.

Tiefenscan

Das Tiefenscannen eignet sich für die Bearbeitung einer großen Anzahl veralteter Dokumente. Die Benutzer können die deepdocs.yml den Nagel auf den Kopf treffen reinit DeepDocs untersucht die gesamte Codebasis, identifiziert alle Dokumente, die aktualisiert werden müssen, und erstellt einen Zweig mit allen Änderungen. Der Bericht listet die aktualisierten Dokumente, den Grund für die Änderung und die zugehörigen Code-Commits auf.

Intelligente Bearbeitung und Berichterstattung

DeepDocs nutzt KI, um den Code in Bezug auf die Dokumentation zu analysieren und nur die notwendigen Teile zu aktualisieren. Wenn sich zum Beispiel eine Funktionssignatur ändert, aktualisiert DeepDocs nur die Beschreibung der zugehörigen Dokumentation, ohne die gesamte Datei neu zu schreiben. Bei jeder Aktualisierung wird ein Bericht erstellt, in dem beschrieben wird, welche Dokumente geändert wurden, warum, und die zugehörigen Code-Commits. Auf diese Weise können die Teams die Richtigkeit der Aktualisierungen schnell überprüfen.

Native Integration von GitHub

DeepDocs wird ohne zusätzliche Tools direkt in GitHub-Workflows eingebettet. Es läuft über GitHub Actions und überwacht Pull Requests und Code Commits. Aktualisierte Dokumentationen werden als Pull-Request eingereicht, was die Überprüfung durch die Teams erleichtert. Die Benutzer können alles tun, ohne GitHub zu verlassen.

Arbeitsablauf

1. Code einreichenEntwickler übertragen normalerweise Code in GitHub-Repositories.
2. automatische ErkennungDeepDocs erkennt Codeänderungen und analysiert die Auswirkungen auf die Dokumentation.
3. Aktualisierungen generierenDeepDocs überträgt aktualisierte Dokumentation und Berichte in den neuen Zweig.
4. Überprüfung und KonsolidierungDas Team überprüft die Pull-Anfrage auf GitHub, bestätigt sie und führt sie zusammen.
5. Manueller Tiefenscan(Optional): Ändern reinit Zeichenfolge, die eine vollständige Korrektur des Dokuments auslöst.

caveat

• Wenn sich die Dokumente und der Code in verschiedenen Repositories befinden, stellen Sie sicher, dass die DeepDocs-Anwendung in beiden Repositories installiert ist, aber konfigurieren Sie nur das Code-Repository mit deepdocs.yml.
• DeepDocs erzeugt kein brandneues Dokument, sondern benötigt ein Ausgangsdokument (z. B. über die Funktion GitHub Kopilot (Erstellt).
• Bei der Aktualisierung der Dokumentation wird das ursprüngliche Markdown-Format beibehalten, das sich für Open-Source-Projekte oder interne Teams eignet.

Anwendungsszenario

1. Wartung von Open-Source-Projekten
   DeepDocs synchronisiert die Dokumentation automatisch, so dass die Betreuer die Dokumentation nicht mehr manuell aktualisieren müssen und neue Entwickler den neuesten Code und die APIs schnell verstehen können.
2. Schnelles, iteratives Entwicklungsteam
   DeepDocs aktualisiert automatisch die README- und API-Dokumentation, so dass sich die Teams auf die Programmierung konzentrieren können, während die Dokumentation korrekt bleibt.
3. Verwaltung von Projekten mit mehreren Lagern
   DeepDocs unterstützt die repositoryübergreifende Synchronisierung für große Projekte, bei denen Code und Dokumente getrennt gespeichert werden. Es überwacht Änderungen am Code-Repository und aktualisiert den Inhalt des Dokumenten-Repository für Microservice-Architektur-Teams.
4. Technische Schuldentilgung
   Ältere Projekte haben oft eine Menge veralteter Dokumentation, und die DeepDocs-Tiefenscan-Funktion behebt diese auf einmal und erstellt klare Änderungsberichte, die den Teams helfen, ihre technischen Schulden schnell zu bereinigen.

QA

1. Verändert DeepDocs die Formatierung oder den Stil des Dokuments?
   Nein. DeepDocs aktualisiert nur den Teil der Dokumentation, der sich auf die Codeänderung bezieht, wobei die ursprüngliche Formatierung, der Ton und die Struktur erhalten bleiben.
2. Welche Arten von Dokumenten werden von DeepDocs unterstützt?
   Unterstützt Dokumentation im Markdown-Format, einschließlich READMEs, API-Referenzen, SDK-Anleitungen und Tutorials, geeignet für die meisten technischen Dokumentationen.
3. Wie löse ich einen Tiefenscan aus?
   Änderungen deepdocs.yml den Nagel auf den Kopf treffen reinit String und Commit scannt DeepDocs die gesamte Codebasis und aktualisiert veraltete Dokumentation.
4. Speichert DeepDocs meinen Code?
   Nein. DeepDocs verarbeitet den Code nur vorübergehend zur Laufzeit und speichert ihn nach der Verarbeitung nicht, um den Datenschutz und die Sicherheit zu gewährleisten.
5. Ist für DeepDocs eine Anfangsdokumentation erforderlich?
   Ja. DeepDocs erstellt keine brandneue Dokumentation, sondern benötigt zunächst eine Ausgangsdokumentation. Es konzentriert sich darauf, die bestehende Dokumentation mit dem Code zu synchronisieren.