Automatisierte Python-Code-Visualisierung. Vierter Teil: Dokumentationsunterstützung

Links zu vorherigen Teilen:

• Teil eins - Einführung, grafische Grundelemente, die zum Erstellen einer grafischen Darstellung des Codes erforderlich sind
• Teil zwei - Implementierung einer grafischen Darstellung des Codegenerators (hauptsächlich in Python), Mikro-Markup-Sprache
• Dritter Teil - Neue Grafikfunktionen

Ein Beispiel für eine Umgebung, die diese grafische Darstellung unterstützt, ist in der folgenden Abbildung dargestellt.


Umgebung zur Unterstützung von grafischem Code

Der vierte Teil des Artikels konzentriert sich auf die Unterstützung des Dokumentationsprozesses.

Um den heißen Brei

Mal sehen, was dem Entwickler in Bezug auf die Arbeit mit der Dokumentation zur Verfügung steht.

Python unterstützt Dokumentationszeilen für Module, Klassen und Funktionen. Das ist gut. Kommentare werden manchmal auch zur Dokumentation verwendet.

Es gibt Dokumentationsgeneratoren wie Sauerstoff und Sphinx . Das ist auch gut.

Manchmal möchten Sie jedoch etwas mehr. Es gibt Zeiten, in denen die Beschreibung einer Funktion oder Klasse zu groß wird und die Dokumentationszeilen (oder Kommentare) unnötig "anschwellen". Die Anzahl der nicht ausführbaren Zeilen beginnt, die Anzahl der ausführbaren Zeilen zu unterdrücken, was das Lesen aufgrund von verschwommenem Code erschweren kann. Ein weiteres Problem sind die verschiedenen Diagramme. Sie können kein fertiges Bild in den Text einfügen. Sie können nur eine Beschreibung des Diagramms einfügen, z. B. ein Plant-UML- Diagramm. Selbst in diesem Fall muss jedoch ein Rendering bereitgestellt werden, was direkt im Programmtext schwierig ist.

Die Lösung des Problems ist einfach: Speichern Sie eine ausführliche Beschreibung in einer separaten Datei und hinterlassen Sie im Code einen Hinweis, dass die Dokumentation vorhanden ist. Eine einzelne Datei kann zum richtigen Zeitpunkt entsprechend gerendert werden. Die Markierung im Code sollte vorzugsweise interaktiv sein, dh mit einem Mausklick einen Übergang zur Dokumentation ermöglichen. Grundsätzlich kann die Markierung im Text des Programms als breiter angesehen werden: Es kann sich um eine URL und eine Stelle in einer anderen Datei des Quelltextes sowie um ein Bild und eine externe Datei mit Dokumentation handeln.

Ein Backlink ist leicht vorstellbar. Angenommen, in der Dokumentation wird eine Klasse aus dem Quellcode eines Programms oder sogar einem bestimmten Codeblock erwähnt. In diesem Fall wäre es auch schön, einen schnellen Übergang zum gewünschten Code zu ermöglichen.

Wir müssen ein weiteres wichtiges Szenario betrachten. Angenommen, während der Entwicklung bestand der Wunsch, eine externe Dokumentationsdatei zu erstellen. Es ist äußerst wünschenswert, dass die organisatorische Frage - wo gespeichert, wie aufgerufen, wie ein Link zur Dokumentation eingefügt wird - so automatisch wie möglich gelöst wird, damit keine unnötige Barriere entsteht, die den aufrichtigen Impuls zur Erstellung von Dokumentation ersticken kann.

Eine gesonderte Diskussion verdient die Frage nach dem Format der Dokumentationsdateien. In letzter Zeit hat Markdown trotz Kritik (zum Beispiel hier ) an Popularität gewonnen. Angenommen, Github zeigt automatisch eine Markdown-Dokumentation an, wenn Sie die Projektseite aufrufen, was sehr praktisch ist. In diesem Fall müssen Sie eine sehr einfache, intuitive Vereinbarung über die Benennung und den Speicherort der Datei treffen. Die Werkzeuge für die Arbeit mit Markdown sind ebenfalls reichlich vorhanden, daher ist dieses Format ein guter Kandidat.

Implementierung in der Codimension IDE

Zusammen mit Text unterstützt die Codimension-IDE die grafische Darstellung von Code. Die IDE unterstützt auch die Markup-Sprache. Daher ist das Hinzufügen eines neuen grafischen Elements zum Anzeigen von Links zur Dokumentation recht einfach.

Zunächst formulieren wir die Anforderungen an neue Funktionen in kompakter Form:

• Unterstützung des Markdown-Formats mit On-the-Fly-Rendering (Anzeigen und Bearbeiten)
• Unterstützen Sie in der grafischen Darstellung des Codes ein neues Element für die Dokumentation mithilfe der CML-Markup-Sprache
• Das grafische Element für die Dokumentation sollte in drei Versionen funktionieren: nur ein Link zu einem anderen Ort; nur Anker für Links von anderen Orten; und Link und Anker
• Der Link kann eine URL sein oder auf eine Datei verweisen (möglicherweise mit einer Linien- oder Ankernummer), die die IDE anzeigen kann
• In Markdown-Unterstützung Plant UML- Diagramme
• Unterstützen Sie die schnelle Erstellung neuer Dokumentationsdateien und Links zu diesen für die grafische Darstellung von Code
• Pflegen Sie den Ausgangspunkt der Dokumentationsdokumentation für ein Projekt, ähnlich wie es Github tut

Markdown und Rendering

Die Codimension-IDE verwendet qutepart als Komponente des Texteditors, und qutepart unterstützt wiederum sofortiges Markdown: Die Hervorhebung der Syntax wurde bereits durchgeführt. Für das automatische Rendern können Sie den gleichen Ansatz wie für Python-Dateien verwenden. Das Hauptfeld ist in zwei Teile gegliedert. Links ist Markdown-Text und rechts wird gerendert:


Markdown mit automatischem Rendering bearbeiten

Das Rendern erfolgt natürlich automatisch. Die IDE definiert eine Pause bei der Textbearbeitung und aktualisiert das Rendering bei Bedarf. In der Markdown-Ansicht wird die linke Seite mit einem Texteditor unterdrückt.

Es war praktisch, die Mistune- Bibliothek zum Rendern zu verwenden , mit der Sie Text schnell in HTML konvertieren können. Bereites HTML wird zur Anzeige an die QT-Komponente gesendet. Die Mistune-Bibliothek erwies sich auch als flexibel genug, um plantUML-Diagrammbeschreibungen eine Erkennung hinzuzufügen. Das Diagramm wird als Codeblock mit der entsprechenden Sprache hinzugefügt, zum Beispiel:


PlantUML-Diagrammerkennung

plantUML unterstützt verschiedene Arten von Diagrammen. Für Codimension ist die Beschreibung des Diagramms transparent, dh es wird nicht analysiert, aber plantUML wird so übertragen, wie es ist. Dementsprechend werden alle unterstützten Typen im Ansichtsfenster angezeigt. Zum Zeitpunkt des Schreibens unterstützte plantUML die folgenden Start- / End-Tags für verschiedene Diagrammtypen:

• @startuml / @enduml
• @startgantt / @endgantt
• @startsalt / @endsalt
• @startmindmap / @endmindmap
• @startwbs / @endwbs
• @startditaa / @endditaa
• @startjcckit / @endjcckit

Die bearbeitbare Markdown-Datei kann mehrere Diagramme sowie vom Netzwerk heruntergeladene Bilder enthalten. Eine häufige Situation ist, wenn sich nur sehr wenig Text ändert und die grafischen Ressourcen unverändert bleiben. Um nicht jedes Mal dasselbe herauszupumpen und keine Diagramme neu zu generieren, musste ein Cache mit ähnlichen Ressourcen implementiert werden.

In der QT-Bibliothek wird die QTextBrowser-Komponente verwendet, die HTML unterstützt. Leider ist der unterstützte HTML-Dialekt begrenzt, so dass es fast unmöglich ist, das Endergebnis zu perfektionieren. Vielleicht kann dieser Mangel in Zukunft behoben werden.

Eingriffe waren auch bei der Verarbeitung von Mausklicks auf Links erforderlich. Einige der folgenden Elemente werden möglicherweise im Link angezeigt:

• externe Ressource (beginnt mit http: // oder mit https: //)
• eine Datei mit einem relativen Pfad vom Projektstamm oder von der aktuellen Datei (praktisch, wenn das Projektverzeichnis im Dateisystem verschoben wird)
• Datei c absoluter Pfad

Wenn es sich um eine Datei handelt, können Sie (optionales Element) entweder die Kennung des Ankers in dieser Datei oder die Zeilennummer angeben. In beiden Fällen werden zusätzliche Informationen verwendet, um die Datei zum gewünschten Speicherort zu scrollen.

Grafisches Element

Es ist sinnvoll, ein grafisches Element mit einem neuen CML-Kommentar einzugeben, ähnlich wie dies beispielsweise für Gruppen bereits geschehen ist. CML unterstützt Attribute, die auch für das neue Grafikelement erforderlich sind.

# cml 1 doc .... 

Ein Link zur Dokumentation ähnelt in gewisser Weise einem Kommentar - er ist keine ausführbare Zeile des Programms, bietet jedoch zusätzliche Informationen zu einem bestimmten Kontext. Die Codimension-IDE erkennt verschiedene Arten von Kommentaren: unabhängig, führend und seitlich. Für die Dokumentation erscheint es ratsam, unabhängige und führende grafische Elemente auf die gleiche Weise wie für Kommentare beizubehalten. Es besteht Verwechslung mit dem Seitenelement für die Dokumentation. Der Punkt ist, wie Nebenkommentare für einen mehrzeiligen Codeblock gerendert werden. Rechts vom Block wird ein Rechteck gezeichnet, das alle Zeilen des Seitenkommentars abdeckt und die Übereinstimmung der Zeilennummern unterstützt. Und was zu tun ist, wenn sich das CML-Dokument in der Mitte des Nebenkommentars trifft, ist nicht ganz klar. Andererseits führt die Verknüpfung immer noch zu einem anderen Ort, sodass die Unterstützung für seitliche CML-Dokumente überflüssig erscheint - der Kontext einer bestimmten Zeile im Codeblock ist sehr eng. Die Unterstützung von seitlichen CML-Dokumenten für Funktionen und Klassen scheint ebenfalls überflüssig zu sein. Daher werden zu diesem Zeitpunkt nur unabhängige und führende CML-Dokumente implementiert. Es ist erwähnenswert, dass diese Funktionalität hinzugefügt werden kann, wenn in Zukunft ein angemessener Bedarf an Unterstützung für laterale CML-Dokumente und eine gute Idee für deren Anzeige besteht.

Lassen Sie uns diskutieren, was in einem grafischen Element angezeigt werden muss. Natürlich benötigen Sie Text für das Element. Der Text wird vom Entwickler festgelegt und zeigt an, worauf der Link verweist. Es wurde bereits erwähnt, dass es wünschenswert ist, mit einem einzigen Klick einen Übergang zur Dokumentation bereitzustellen. Der Text des Grafikelements ist nicht geeignet, da die Kontinuität zwischen dem Verhalten anderer Elemente beachtet werden muss - durch Klicken mit der Maus wird das Grafikelement ausgewählt. Die Lösung des Problems ist jedoch einfach: Sie können beispielsweise links neben dem Text ein Symbol hinzufügen. Wenn Sie auf das Symbol klicken, wird der Übergang angezeigt.

Jetzt ist die Liste der Attribute für den CML-Dokumentkommentar klar:

• Link - Link zu einem anderen Ort
• Anker - Ankerkennung für Links von anderen Orten
• Titel - Text, der im grafischen Element angezeigt werden soll
• bg, fg, border - individuelle Farben des Elements, wenn es auf besondere Weise hervorgehoben werden muss

Mindestens eines der beiden Attribute Link und Anker muss vorhanden sein. Ohne sie macht ein solcher CML-Dokumentkommentar wenig Sinn. Andere Attribute sind optional. Der Text ist möglicherweise überhaupt nicht und die Farben sind möglicherweise Standard.

Hier ist ein Beispiel für Code, der das CML-Dokument und seine grafische Darstellung verwendet:


Unabhängige und führende Kommentare zu CML-Dokumenten

Der Unterschied zwischen führenden und unabhängigen Elementen besteht nur darin, wo der Konnektor führt: entweder zu einem bestimmten Block oder zu einem Konnektor zwischen Blöcken.

Wenn sich der Mauszeiger über dem Symbol befindet und das Element über ein Verknüpfungsattribut verfügt, ändert sich die Form des Cursors, was darauf hindeutet, dass ein Klick ausgeführt wird.

Das grafische Element unterstützt auch das Kontextmenü. Zum Anzeigen oder Bearbeiten von Elementattributen, einschließlich Farben, und zum Löschen eines Elements steht eine Option zur Verfügung.

Andere grafische Elemente

Fast alle anderen Elemente in der grafischen Darstellung des Codes können dokumentiert sein (Ausnahmen sind beispielsweise Kommentare und Dokumentzeichenfolgen). Daher haben sie die Möglichkeit, ein Dokumentationselement über das Kontextmenü zu erstellen.


Kontextmenü zum Arbeiten mit Dokumentation

Es gibt nur zwei Möglichkeiten. Der erste "Dokumentlink / Anker hinzufügen / bearbeiten ..." führt zu einem modalen Dialog zur manuellen Eingabe der Link-, Anker- und Titelattribute. Hier hat der Entwickler die völlige Freiheit, wohin der Link gesendet, wo die Datei abgelegt werden soll usw.

Die zweite Option ist interessanter. Der Name des Elements ist aufgrund der ausgeführten Aktionen lang: "Dokumentdatei erstellen, Link hinzufügen und zur Bearbeitung öffnen". Alle Aktionen werden automatisch ohne Eingabe ausgeführt, sodass Sie das organisatorische Problem schnell lösen können:

• Es wird eine Entscheidung über die Datei getroffen, in der sich die Dokumentation befindet (wir werden unten betrachten).
• # cml 1 doc ... im Quelltext # cml 1 doc ... , das auf die Dokumentationsdatei verweist und den generierten Anker und Text generiert. Der Anker wird als doc <Zufallszahl> generiert. Fester Text: Siehe Dokumentation
• Wenn die Dokumentationsdatei bereits vorhanden ist, wird sie zur Bearbeitung in einer neuen Registerkarte geöffnet
• Wenn die Dokumentationsdatei nicht vorhanden ist, wird sie erstellt, zur Bearbeitung in einer neuen Registerkarte geöffnet und dem Bearbeitungspuffer wird eine kurze Hilfe hinzugefügt, einschließlich des Verweises auf den gerade eingefügten Kommentar # cml 1 doc ...

Die Entscheidung über die Datei hängt davon ab, ob das Projekt geladen wird. Wenn geladen, wird das Unterverzeichnis doc im Projektstamm erstellt und anschließend der relative Pfad vom Projektstamm zur Quelltextdatei. Der Dateiname wird gebildet, indem die Erweiterung durch .md ersetzt wird. Zum Beispiel, wenn sich ein Projekt in befindet

 /home/me/myProject 

Für die Projektdatei wird eine Dokumentation hinzugefügt

 /home/me/myProject/src/utils.py 

Eine Dokumentationsdatei wird erstellt

 /home/me/myProject/doc/src/utils.md 

Daher wiederholt die Struktur der Dokumentation für den Quellcode die Struktur des Quellcodes, und selbst ein kurzer Blick auf das Unterverzeichnis doc im Projekt reicht für eine intuitive Navigation aus. Das Schema scheint für das Standardverhalten angemessen zu sein, was die Arbeit mit der Dokumentation beschleunigt.

Wenn das Projekt nicht geladen ist, wird das Unterverzeichnis doc neben der Datei und darin die Datei mit der geänderten Erweiterung in .md erstellt. Ein solches Szenario erscheint jedoch unwahrscheinlich. Wenn es sich um Dokumentation handelt, handelt es sich mit ziemlicher Sicherheit um eine Arbeit an einem Projekt und nicht um eine separate Datei.

Natürlich können Sie jederzeit automatisch generierte Elemente ändern, indem Sie # cml 1 doc ... in einem Texteditor oder in einem Dialogfeld in einer grafischen Darstellung bearbeiten.

Ausgangspunkt der Projektdokumentation

Warum brauche ich einen Dokumentationsstartpunkt? Meiner Meinung nach kann dies denjenigen, die es zuerst öffnen, den Einstieg in das Projekt erleichtern. Zum Beispiel bei der Erweiterung der Zusammensetzung des Entwicklungsteams oder für Benutzer des Projekts. Stellen Sie sich vor, das Projekt verfügt über eine Dokumentation und besteht aus einer großen Anzahl von Dateien. Wo soll ich anfangen? Wie ist die Dokumentation aufgebaut? Anstatt zu spekulieren und sie dann zu überprüfen, wäre es bequemer, eine explizite Angabe des empfohlenen Einstiegspunkts zu haben.

Hier können Sie den Github-Ansatz etwas erweitern, sodass sowohl die Standardoptionen als auch die spezifischen Optionen für die Dokumentationsorganisation funktionieren. Wenn nichts gesagt wird, suchen wir im Projektstamm nach der Datei README.md. Die Eigenschaften des Projekts können um ein weiteres Feld erweitert werden, das eine bestimmte Datei des Startpunkts der Dokumentation angibt.

Es gibt zwei Möglichkeiten, die Projektdokumentation zu öffnen. Der Symbolleiste des IDE-Hauptfensters wurde eine Schaltfläche mit dem Markdown-Symbol hinzugefügt. Wenn Sie darauf klicken, wird die Dokumentationsdatei im Anzeigemodus geöffnet, sofern verfügbar. Wenn keine Datei vorhanden ist, wird der Speicherort der Dokumentationsdatei angeboten und im Bearbeitungsmodus wird eine neue Registerkarte mit dem Text geöffnet - ein Stub. Die zweite Option ist ein Link zur Begrüßungsseite von Codimension , die angezeigt wird, wenn keine andere geöffnete Registerkarte vorhanden ist. Der Begleittext enthält Wörter zur Projektdokumentation und einen Link, falls die Dokumentation gefunden wird. Diese Begrüßungsseite wird dem Benutzer angezeigt, der das Projekt zum ersten Mal geöffnet hat.

Testen in der Praxis

Die oben beschriebene Funktionalität wurde an Katzen getestet, dh im Projekt der Codimension IDE selbst . Jetzt enthält das Installationspaket eine Dokumentation, die im Markdown-Format erstellt wurde. Diese Funktionsprüfung kann nicht als vollständig angesehen werden, da die Dokumentation für den Endbenutzer und nicht per Code erstellt wurde. Der Gesamteindruck, dass es sich herausstellte, ist jedoch durchaus akzeptabel.

Offene Fragen

Benötige ich Unterstützung für seitliche CML-Dokumentelemente? Wenn ja, wie zeichnet man sie dann zum Beispiel für einen solchen Fall:

 a = 10 # Comment line 1 b = 20 # cml 1 doc title="my side doc" c = 30 # cml+ link="http://codimension.org" d = 40 # Comment line 4 # Comment line 5 

Man könnte plantUML-Diagrammbeschreibungen direkt in den Dokumentationszeilen erkennen. Wenn eine solche Unterstützung erfolgt, wie werden diese Diagramme dann in der grafischen Darstellung des Codes angezeigt?

Um die Erstellung von plantUML-Diagrammen zu erleichtern, könnte dieses Szenario Funktionen hinzufügen:

• Der Benutzer klickt mit der rechten Maustaste auf die Klasse in der grafischen Darstellung des Codes oder in einem anderen Fenster (Liste der Projektklassen, Inhalt der strukturierten Datei).
• Wählt im Kontextmenü ein Element aus, um eine Klassenbeschreibung im plantUML-Format zu generieren
• Die generierte Beschreibung wird in einem Textpuffer gespeichert.
• Der Benutzer fügt Text in das Markdown-Dokument ein und ändert ihn gegebenenfalls

Die Vitalität eines solchen Szenarios ist fraglich, obwohl es trivial ist, es umzusetzen.

Wenn Sie Ideen haben, teilen Sie diese bitte in den Kommentaren mit.