Doxygen/de

Über
Doxygen ist ein beliebtes Werkzeug zur Generierung von Dokumentation aus kommentierten C++ Quellen; es unterstützt auch andere gängige Programmiersprachen wie C#, PHP, Java und Python. Besuche die Doxygen Website, um mehr über das System zu erfahren, und konsultiere das Doxygen Handbuch für die vollständigen Informationen.

Doxygen und FreeCAD
Dieses Dokument gibt eine kurze Einführung in Doxygen, insbesondere wie es in FreeCAD zur Dokumentation seiner Quellen verwendet wird. Auf der Seite Quelldokumentation findest Du Anweisungen zum Erstellen der FreeCAD Dokumentation, die ebenfalls online auf der FreeCAD API Website bereitgestellt wird.



Doxygen mit C++ Code
Der Abschnitt Getting started (Step 3) im Doxygen Handbuch erwähnt die grundlegenden Möglichkeiten der Dokumentation der Quellen.

Für Mitglieder, Klassen und Namensräume gibt es grundsätzlich zwei Möglichkeiten:
 * 1) Platziere einen speziellen "Dokumentationsblock" (einen kommentierten Absatz) vor der Deklaration oder Definition der Funktion, des Elements, der Klasse oder des Namensraums. Bei Datei-, Klassen- und Namensraumelementen (Variablen) ist es auch erlaubt, die Dokumentation direkt nach dem Element zu platzieren. Siehe Abschnitt Spezielle Kommentarblöcke im Handbuch, um mehr über diese Blöcke zu erfahren.
 * 2) Platziere einen speziellen Dokumentationsblock an einer anderen Stelle (eine andere Datei oder einen anderen Ort in der gleichen Datei) und füge einen "Strukturbefehl" in den Dokumentationsblock ein. Ein Strukturbefehl verknüpft einen Dokumentationsblock mit einer bestimmten zu dokumentierenden Einheit (Funktion, Element, Variable, Klasse, Namensraum oder Datei). Siehe Abschnitt Dokumentation an anderer Stelle im Handbuch, um mehr über Strukturbefehle zu erfahren.

Hinweis:
 * Der Vorteil der ersten Option ist, dass du den Namen der Einheit (Funktion, Element, Variable, Klasse oder Namensraum) nicht wiederholen musst, da Doxygen den Code analysiert und die relevanten Informationen extrahiert.
 * Dateien können nur mit der zweiten Option dokumentiert werden, da es keine Möglichkeit gibt, einen Dokumentationsblock vor eine Datei zu stellen. Natürlich benötigen Dateimitglieder (Funktionen, Variablen, Typedefinitionen, Definitionen) keinen expliziten Strukturbefehl; einfach einen Dokumentationsblock vor oder nach ihnen zu setzen, wird gut funktionieren.

Erster Stil: Dokumentationsblock vor dem Kode
Normalerweise möchtest du den Code in der Kopfzeilendatei dokumentieren, kurz vor der Klassendeklaration oder dem Funktionsprototyp. Dadurch bleiben Deklaration und Dokumentation dicht beieinander, so dass es einfach ist, letztere zu aktualisieren, wenn sich die erste ändert.

Der spezielle Dokumentationsblock beginnt wie ein Kommentar im C-Stil, hat aber ein zusätzliches Sternchen, also ; der Block endet mit einem passenden. Eine Alternative ist die Verwendung von Kommentaren im C++-Stil mit einem zusätzlichen Schrägstrich, also.

Zweiter Stil: Dokumentationsblock an anderer Stelle
Alternativ kann die Dokumentation auch in einer anderen Datei (oder in derselben Datei oben, unten oder wo auch immer) abgelegt werden, weg von der Klassendeklaration oder dem Funktionsprototyp. In diesem Fall hast du duplizierte Informationen, einmal in der eigentlichen Quelldatei und einmal in der Dokumentationsdatei.

Erste Datei, :

Zweite Datei, :

In diesem Fall wird der Strukturbefehl verwendet, um anzugeben, welche Quelldatei dokumentiert wird; ein Strukturbefehl  zeigt an, dass der folgende Code eine Funktion ist, und der Befehl  wird verwendet, um eine kleine Beschreibung dieser Funktion zu geben.

Diese Art der Dokumentation einer Quelldatei ist nützlich, wenn du nur Dokumentation zu deinem Projekt hinzufügen möchtest, ohne echten Code hinzuzufügen. Wenn du einen Kommentar-Block in eine Datei mit einer der folgenden Erweiterungen, , oder  platzierst, dann wird Doxygen die Kommentare analysieren und die entsprechende Dokumentation erstellen, aber es wird diese Hilfsdatei aus der Dateiliste ausblenden.

Das FreeCAD Projekt fügt in vielen Verzeichnissen mehrere Dateien mit der Endung hinzu, um eine Beschreibung oder Beispiele für den dortigen Code zu liefern. Es ist wichtig, dass solche Dateien korrekt in einer Gruppe oder einem Namensraum kategorisiert werden, für die Doxygen einige Hilfsbefehle wie, , , und bereitstellt.

Beispiel ; diese Datei im FreeCAD Quellbaum gibt eine kurze Erklärung des Namensraums.

Ein weiteres Beispiel ist die Datei. Vor den Implementierungsdetails der Methoden gibt es einen Dokumentationsblock, der einige Details des Befehlsrahmens von FreeCAD erklärt. Es verfügt über verschiedene Befehle, um die Dokumentation zu strukturieren. Es beinhaltet sogar Beispielcode, der in einem Paar von und  Schlüsselwörtern eingeschlossen ist; wenn die Datei von Doxygen verarbeitet wird, wird dieses Code-Beispiel speziell formatiert, um sich abzuheben. Das Schlüsselwort wird an mehreren Stellen verwendet, um Links zu benannten Abschnitten, Unterabschnitten, Seiten oder Ankern an anderer Stelle in der Dokumentation zu erstellen. Ebenso drucken die Befehle oder  "Siehe auch" und stellen einen Link zu anderen Klassen, Funktionen, Methoden, Variablen, Dateien oder URLs dar. Beispiel

Beispiel aus dem VTK Projekt
Dies ist ein Beispiel aus VTK, einer 3D Visualisierungsbibliothek, die zur Darstellung wissenschaftlicher Daten wie Finite Elemente Ergebnisse und Punktwolkeninformationen verwendet wird.

Eine Klasse zum Speichern einer Sammlung von Koordinaten wird in einer C++ Kopfzeilendatei definiert. Der obere Teil der Datei wird kommentiert, und es werden einige Schlüsselwörter verwendet, wie, , und , um wichtige Teile zu kennzeichnen. Innerhalb der Klasse, vor den Prototypen der Klassenmethode, erklärt ein Block aus kommentiertem Text, was die Funktion tut und welche Argumente sie hat.
 * Quellcode von vtkArrayCoordinates.h.
 * Doxygen hat die Dokumentation für die vtkArrayCoordinates class erstellt.

Zusammenstellung der Dokumentation


Um die Quellcode Dokumentation zu erstellen, gibt es zwei grundlegende Schritte:
 * 1) Erstelle eine Konfigurationsdatei, um zu steuern, wie Doxygen die Quelldateien verarbeiten soll.
 * 2) Führe  in dieser Konfiguration aus.

Der Prozess wird im Folgenden beschrieben.


 * Stelle sicher, dass die Programme und  in Deinem System vorhanden sind. Es wird auch empfohlen, das Programm  von Graphviz zu verwenden, um Diagramme mit den Beziehungen zwischen Klassen und Namensräumen zu erzeugen. Auf Linux Systemen können diese Programme über Ihren Paketmanager installiert werden.


 * Stelle sicher, dass Du Dich im gleichen Ordner wie Deine Quelldateien befindest, oder im Toplevel Verzeichnis Deines Quellbaums, wenn Du viele Quelldateien in verschiedenen Unterverzeichnissen hast.


 * Führe aus, um eine Konfigurationsdatei namens  zu erstellen. Wenn Du diesen Namen weglässt, wird er standardmäßig auf  ohne Erweiterung gesetzt.
 * Dies ist eine große, einfache Textdatei, die viele Variablen mit ihren Werten enthält. Im Doxygen Handbuch werden diese Variablen als "Tags" bezeichnet. Die Konfigurationsdatei und alle Tags sind im Abschnitt Konfiguration des Handbuchs ausführlich beschrieben. Du kannst die Datei mit einem beliebigen Texteditor öffnen und den Wert jedes Tags nach Bedarf bearbeiten. In der gleichen Datei kannst du Kommentare lesen, die jedes der Tags und seine Standardwerte erklären.


 * Anstatt einen Texteditor zu verwenden, kannst du starten, um viele Tags gleichzeitig zu bearbeiten. Mit dieser Schnittstelle kannst du viele Eigenschaften definieren, wie z.B. Projektinformationen, Art der Ausgabe (HTML und LaTeX), Verwendung von Graphviz zur Erstellung von Diagrammen, Warnmeldungen zur Anzeige, Dateimuster (Erweiterungen) zum Dokumentieren oder Ausschließen, Eingabefilter, optionale Kopf- und Fußzeilen für die von HTML generierten Seiten, Optionen für LaTeX-, RTF-, XML- oder Docbook-Ausgaben und viele andere Optionen.


 * Eine weitere Möglichkeit besteht darin, die Konfigurationsdatei von Grund auf neu zu erstellen und nur die Tags hinzuzufügen, die du mit einem Texteditor willst.
 * Nachdem die Konfiguration gespeichert wurde, kannst du Doxygen auf dieser Konfigurationsdatei ausführen.


 * Die erzeugte Dokumentation wird in einem Ordner namens erstellt. Es wird aus vielen HTML Seiten, PNG Bildern für Grafiken, Cascading Style Sheets, Javascript Dateien  und möglicherweise vielen Unterverzeichnissen mit mehr Dateien je nach Größe Ihres Codes bestehen. Der Einstiegspunkt in die Dokumentation ist , den du mit einem Webbrowser öffnen kannst.

Wenn du neue Klassen, Funktionen oder eine ganze neue Arbeitsbereiche schreibst, wird empfohlen, regelmäßig auszuführen, um sicherzustellen, dass die Dokumentationsblöcke Markdown und Spezielle Befehle korrekt gelesen werden und dass alle öffentlichen Funktionen vollständig dokumentiert sind. Bitte lies auch die Dokumentationshinweise im Quellcode.

Bei der Generierung der kompletten FreeCAD Dokumentation führe  nicht direkt aus. Stattdessen verwende das Projekt, um die Build Umgebung zu konfigurieren, und löst dann die Kompilierung der FreeCAD Quellen und der Doxygen Dokumentation aus; dies wird auf der Seite Quell Dokumentation erläutert.

Doxygen Auszeichnung
Alle Doxygen Befehlsdokumentation beginnt mit einem Backslash oder einem at Symbol, je nach Wunsch. Normalerweise wird der Backslash verwendet, aber gelegentlich wird der  verwendet, um die Lesbarkeit zu verbessern.

Die Befehle können ein oder mehrere Argumente haben. Im Doxygen Handbuch werden die Argumente wie folgt beschrieben.
 * Wenn Klammern verwendet werden, ist das Argument ein einzelnes Wort.
 * Wenn Klammern verwendet werden, erstreckt sich das Argument bis zum Ende der Zeile, in der der Befehl gefunden wurde.
 * Wenn  Klammern verwendet werden, verlängert sich das Argument bis zum nächsten Absatz. Absätze werden durch eine Leerzeile oder durch ein Abschnittskennzeichen begrenzt.
 * Wenn Klammern verwendet werden, ist das Argument optional.

Einige der häufigsten Schlüsselwörter, die in der FreeCAD Dokumentation verwendet werden, sind hier aufgeführt. , siehe \addtogroup, undGruppierung. , siehe\subsection; startet einen Unterabschnitt. , siehe\return; gibt den Rückgabewert an.
 * , siehe \defgroup, undGruppierung.
 * , siehe\ingroup, undGruppierung.
 * , siehe \author; gibt den Autor dieses Stückes Code an.
 * , siehe \brief; beschreibt kurz die Funktion.
 * , siehe \file; dokumentiert eine Quell- oder Header-Datei.
 * , siehe \page; stellt die Informationen auf eine separate Seite, nicht direkt in Bezug stehend mit einer bestimmten Klasse, Datei oder einem Mitglied.
 * , siehe\package; zeigt die Dokumentation für ein Java Paket an (wird aber auch mit Python verwendet).
 * , siehe \fn; dokumentiert eine Funktion.
 * , siehe \var; dokumentiert eine Variable; sie entspricht, , und.
 * , siehe\section; startet einen Abschnitt.
 * , siehe\namespace; zeigt Informationen für einen Namensraum an.
 * , und, siehe\cond; definiert einen Block, der bedingt dokumentiert oder weggelassen werden soll.
 * , siehe\a; zeigt das Argument kursiv zur Hervorhebung an.
 * , siehe\param; gibt den Parameter einer Funktion an.
 * , siehe \sa; druckt "Siehe auch".
 * , siehe\note; fügt einen Absatz hinzu, der als Notiz verwendet werden soll.

Markdown Unterstützung
Seit Doxygen 1.8 wird die Markdown Syntax in Dokumentationsblöcken erkannt. Markdown ist eine minimalistische Formatierungssprache, die von einfachen Text Emails inspiriert ist, die, ähnlich wie die Wiki Syntax, einfach und lesbar sein soll, ohne komplizierten Code wie den in HTML, LaTeX oder Doxygens eigenen Befehlen zu benötigen. Markdown hat bei freier Software an Popularität gewonnen, insbesondere in Online Plattformen wie Github, da es die Erstellung von Dokumentation ohne komplizierten Code ermöglicht. Weitere Informationen finden sich im Abschnitt Markdown Support im Doxygen Handbuch. Besuche die Markdown Webseite, um mehr über den Ursprung und die Philosophie von Markdown zu erfahren.

Doxygen unterstützt einen Standardsatz von Markdown Anweisungen sowie einige Erweiterungen wie z.B. Github Markdown. Im Folgenden werden einige Beispiele für die Formatierung von Markdown vorgestellt.

Das Folgende ist Standard Markdown. {{Code|code= Hier ist der Text für einen Absatz.

Wir machen mit mehr Text in einem anderen Absatz weiter.

Dies ist eine Level 1 Kopfzeile

=
===========

Dies ist eine Level 2 Kopfzeile.


 * 1) Dies ist ein Level 1 Kopfteil


 * 1) Dies ist ein Level 3 Kopfteil #######

> Dies ist ein Blockzitat > über mehrere Linien hinweg

- Punkt 1

Mehr Text für dieses Element.

- Punkt 2 * Verschachtelte Listenelemente. * ein weiteres verschachteltes Element. - Punkt 3

1. Erstes Element. 2. Zweites Element.


 * einzelne Sternchen: Hervorhebung*

_single underscores_

**double asterisks: strong emphasis**

__double underscores__

Dies ist ein normaler Abschnitt

Dies ist ein Codeblock

Wir fahren mit einem normalen Absatz fort.

Use the `printf` function. Inline `code`.

[The link text](http://example.net/)

![Caption text](/path/to/img.jpg)

 }}

Die folgenden sind Markdown Erweiterungen. [TOC]

Erste Kopfzeile | Zweite Kopfzeile - | - Zellinhalt | Zellinhalt Zellinhalt | Zellinhalt

~ {.py} class Dummy: pass ~
 * 1) Eine Klasse

~ {.c} int func(int a, int b) { return a*b; } ~

``` int func(int a, int b) { return a*b; } ```

Zerteilen von Dokumentationsblöcken
Der Text in einem speziellen Dokumentationsblock wird analysiert, bevor er in die HTML- und LaTeX Ausgabedateien geschrieben wird. Beim Zertilen (engl.: Parsen) finden die folgenden Schritte statt:
 * Die Markdown Formatierung wird durch entsprechendes HTML oder spezielle Befehle ersetzt.
 * Die speziellen Befehle innerhalb der Dokumentation werden ausgeführt. Siehe Abschnitt Spezielle Befehle im Handbuch für eine Erklärung der einzelnen Befehle.
 * Wenn eine Zeile mit einem Leerzeichen beginnt, gefolgt von einem oder mehreren Sternchen und dann optional mehr Leerzeichen, dann werden alle Leerzeichen und Sternchen entfernt.
 * Alle resultierenden Leerzeilen werden als Absatztrennzeichen behandelt.
 * Links werden automatisch für Wörter erstellt, die den dokumentierten Klassen oder Funktionen entsprechen. Wenn dem Wort ein Prozentsymbol vorangestellt ist, wird dieses Symbol entfernt und es wird keine Verknüpfung für das Wort erstellt.
 * Links werden erstellt, wenn bestimmte Muster im Text gefunden werden. Weitere Informationen finden Sie im Abschnitt Automatische Linkerzeugung im Handbuch.
 * HTML-Tags, die sich in der Dokumentation befinden, werden interpretiert und für die LaTeX Ausgabe in LaTeX Äquivalente umgewandelt. Siehe den Abschnitt HTML-Befehle im Handbuch für eine Erklärung der einzelnen unterstützten HTML-Tags.

Doxygen mit Python Code
Doxygen funktioniert am besten für statisch typisierte Sprachen wie C++. Es kann aber auch eine Dokumentation für Python-Dateien erstellen.

Es gibt zwei Möglichkeiten, Dokumentationsblöcke für Python zu schreiben:
 * 1) Der pythonische Weg, mit "docstrings", d.h. ein Textblock, der von   unmittelbar nach der Klassen- oder Funktionsdefinition umgeben ist.
 * 2) Der Doxygen Weg, bei dem Kommentare vor die Klassen- oder Funktionsdefinition gestellt werden; in diesem Fall werden doppelte Hash-Zeichen  verwendet, um den Dokumentationsblock zu starten, und dann kann ein einzelnes Hash Zeichen in nachfolgenden Zeilen verwendet werden.

Hinweis:
 * Die erste Option wird bevorzugt, um PEP8, PEP257 und die meisten Stilrichtlinien für das Schreiben von Python zu erfüllen (siehe 1, 2). Es wird empfohlen, diesen Stil zu verwenden, wenn du beabsichtigst, dokumentierte Quellen mit Sphinx zu erzeugen, einem sehr gebräuchlichen Werkzeug zur Dokumentation von Python Code. Wenn Du diesen Stil verwendest, kann Doxygen die Kommentare wörtlich extrahieren, aber spezielle Doxygen Befehle, die mit oder  beginnen, funktionieren nicht.
 * Die zweite Option ist nicht der traditionelle Python Stil, aber sie erlaubt es Dir, die speziellen Befehle von Doxygen wie und  zu verwenden.

Erster Stil: Pythonische Dokumentation
Im folgenden Beispiel steht am Anfang eine docstring, um den allgemeinen Inhalt dieses Moduls (Datei) zu erklären. Dann erscheinen docstrings innerhalb der Funktions-, Klassen- und Klassenmethodendefinitionen. Auf diese Weise extrahiert Doxygen die Kommentare und präsentiert sie so, wie sie sind, ohne Änderungen.

Zweiter Stil: Dokumentationsblock vor dem Code
Im folgenden Beispiel beginnen die Dokumentationsblöcke mit doppelten Hashzeichen. Am Anfang erscheint eine, um den allgemeinen Inhalt dieses Moduls (Datei) zu erklären. Dann gibt es Blöcke vor den Definitionen von Funktions-, Klassen- und Klassenmethoden, und es gibt einen Block nach einer Klassenvariablen. Auf diese Weise extrahiert Doxygen die Dokumentation, erkennt die speziellen Befehle, , und und formatiert den Text entsprechend.

Zusammenstellung der Dokumentation
Die Kompilierung der Dokumentation erfolgt wie bei für C++ Quellen. Wenn sich beide Python Dateien, und, mit eigenem Kommentarstil im gleichen Verzeichnis befinden, werden beide verarbeitet.

Die Dokumentation sollte ähnliche Informationen wie die folgenden enthalten und entsprechende Verknüpfungen zu den einzelnen Modulen und Klassen herstellen.

Umwandlung des pythonischen Stils in den Doxygen Stil
Im vorherigen Beispiel zeigt die Python Datei, die in einem Doxygen Stil kommentiert wird, detailliertere Informationen und Formatierungen für ihre Klassen, Funktionen und Variablen. Der Grund dafür ist, dass dieser Stil es Doxygen erlaubt, die speziellen Befehle zu extrahieren, die mit oder  beginnen, während der Pythonischer Stil dies nicht tut. Daher wäre es wünschenswert, den pythonischen Stil in den Doxygen Stil zu konvertieren, bevor die Dokumentation erstellt wird. Dies ist mit einem zusätzlichen Python-Programm namens doxypypy möglich. Dieses Programm ist inspiriert von einem älteren Programm namens doxypy, das den Python  nehmen und in die Doxygen Kommentarblöcke konvertieren würde, die mit einem Doppelhash  beginnen. Doxypypy geht noch weiter, da es die docstrings analysiert und interessante Elemente wie Variablen und Argumente extrahiert und sogar Doktests (Beispielcode in den docstrings).

Doxypypy kann mit, dem Installationsprogramm für Python Pakete, installiert werden.

Wenn der Befehl ohne die Option  verwendet wird, benötigt er Superuser (root) Rechte, um das Paket zu installieren, aber das ist in den meisten Fällen nicht erforderlich; verwende root Rechte nur, wenn Du sicher bist, dass das Paket nicht mit den von der Distribution bereitgestellten Paketen kollidiert.

Wenn das Paket als Benutzer installiert wurde, kann es sich in Deinem Heimatverzeichnis befinden, z.B. in. Wenn sich dieses Verzeichnis nicht im deines Systems befindet, wird das Programm nicht gefunden. Füge daher das Verzeichnis der Variablen hinzu, entweder in deiner  Datei oder in deiner  Datei.

Alternativ kannst du auch einen symbolischen Link zum Programm erstellen und den Link in ein Verzeichnis legen, das bereits im  enthalten ist.

Sobald das Programm installiert und vom Terminal aus zugänglich ist, kann eine Python Datei mit pythonischen  docstrings  mit den folgenden Anweisungen in den Doxygen Stil umformatiert werden. Das Programm gibt den formatierten Code als Standardausgabe aus, also leite diese Ausgabe in eine neue Datei um.

Die Originaldatei hat oben einen Kommentar, der das Modul oder den Namensraum angibt, der durch die Datei beschrieben wird. Dieses Schlüsselwort wird nicht interpretiert, wenn dreifache Anführungszeichen im Kommentarblock verwendet werden.

In der neuen Datei wird der Kommentarstil so geändert, dass die Zeile wird, die nun von Doxygen interpretiert wird. Um jedoch korrekt interpretiert zu werden, muss das Argument manuell bearbeitet werden, um dem neuen Modul (Datei-) Namen zu entsprechen; danach sollte die Zeile sein.

(das Obere wird manuell bearbeitet, der Rest bleibt gleich)

Um zu kompilieren, erstelle die Konfiguration und führe  im Toplevel Verzeichnis aus, das die Dateien enthält.

Die Dokumentation sollte ähnliche Informationen wie die folgenden enthalten und entsprechende Verknüpfungen zu den einzelnen Modulen herstellen.

Fliegendes konvertieren des Kommentarstils
Im vorherigen Beispiel wurde die Konvertierung der Dokumentationsblöcke manuell mit nur einer Quelldatei durchgeführt. Im Idealfall soll diese Konvertierung automatisch, fliegend, mit einer beliebigen Anzahl von Python Dateien erfolgen. Dazu muss die Doxygen Konfiguration entsprechend angepasst werden.

Verwende zunächst nicht direkt das Programm, sondern erstelle die Konfigurationsdatei mit , bearbeite dann die erstellte und ändere das folgende Tag.

Was dies bewirkt, ist, dass Dateien, die dem Muster entsprechen, alle Dateien mit einer Erweiterung, die auf endet, das Programm  durchlaufen. Jedes Mal, wenn Doxygen auf eine solche Datei im Quellbaum trifft, wird der Dateiname als erstes Argument an dieses Programm übergeben.

Das Programm ist standardmäßig nicht vorhanden; es sollte als Shell Skript erstellt werden, um  mit den entsprechenden Optionen auszuführen und eine Datei als erstes Argument zu verwenden.

Nachdem du dieses Shell Skript gespeichert hast, stelle sicher, dass es über Ausführungsrechte verfügt und sich in einem Verzeichnis befindet, das sich im deines Systems befindet.

Auf Windows Systemen kann eine Batch Datei auf ähnliche Weise verwendet werden.

Wenn diese Konfiguration abgeschlossen ist, kann der Befehl ausgeführt werden, um die Dokumentation wie gewohnt zu generieren. Jede Python Datei, die Pythonic  verwendet, wird spontan neu formatiert, um Kommentare im Stil von  zu verwenden, und dann von Doxygen verarbeitet, das nun in der Lage ist, das special commands und Mardown syntax zu interpretieren. Der ursprüngliche Quellcode wird nicht geändert, und es muss keine temporäre Datei mit einem anderen Namen erstellt werden, wie in der vorherige Abschnitt; wenn also eine Anweisung gefunden wird, muss sie nicht manuell geändert werden.

Beachte, dass bestehende Python Dateien, die bereits den Stil für ihre Kommentarblöcke verwenden, vom Filter  nicht beeinflusst werden und von Doxygen normal verarbeitet werden.



Python Code Qualitätsprüfung
Um die automatische Konvertierung von Dokumentationsblöcken nutzen zu können, ist es wichtig, dass die originalen Python Quellen korrekt geschrieben sind und den pythonischen Richtlinien in PEP8 und PEP257 entsprechen. Schlampig geschriebener Code führt dazu, dass bei der Verarbeitung der Datei fehlschlägt, so dass Doxygen die Dokumentation nicht korrekt formatieren kann.

Die folgenden Kommentarstile erlauben kein Zerlegen der docstrings durch, daher sollten sie vermieden werden.

Verwende immer dreifache Anführungszeichen für die docstrings und stelle sicher, dass sie unmittelbar der Klassen- oder Funktionsdeklaration folgen.

Es ist auch eine gute Idee, die Qualität Ihres Python Codes mit einem Werkzeug wieflake8 (Gitlab) zu überprüfen. Flake8 kombiniert im Wesentlichen drei Werkzeuge, Pyflakes, Pycodestyle (früher pep8) und den McCabe complexity checker, um den richtigen pythonischen Stil durchzusetzen.

Um alle Dateien innerhalb eines Quellbaums zu überprüfen, verwende.

Wenn das Projekt es verlangt, können einige zu strenge Code Überprüfungen ignoriert werden. Die Fehlercodes können in der Pycodestyle Dokumentation eingesehen werden.

In ähnlicher Weise ist ein Programm, das in erster Linie prüft, ob Kommentare mit PEP257 übereinstimmen, Pydocstyle. Die Fehlercodes können in der Pydocstyle Dokumentation eingesehen werden.

Verwende es auch mit, um docstring Überprüfungen für alle Quelldateien durchzuführen.

Quelldokumentation mit Sphinx
Sphinx ist das beliebteste System zur Dokumentation von Python Quellcode. Da die Kernfunktionen und Arbeitsbereiche von FreeCAD jedoch in C++ geschrieben sind, wurde davon ausgegangen, dass Doxygen ein besseres Dokumentationswerkzeug für dieses Projekt ist.

Während Sphinx Python docstrings nativ analysieren kann, erfordert es etwas mehr Arbeit, C++ Quelltexte zu analysieren. Das Projekt Breathe (Github) ist ein Versuch, die Lücke zwischen Sphinx und Doxygen zu schließen, um sowohl Python- als auch C++ Quellcode Dokumentation in das gleiche System zu integrieren. Zuerst muss Doxygen konfiguriert werden, um eine XML Datei auszugeben; die XML Ausgabe wird dann von Breathe gelesen und in einen geeigneten Input für Sphinx umgewandelt.

Weitere Informationen zu diesem Prozess findest du in der Dokumentation von Breathe unter Quick start guide.

Siehe diese Antwort in Stackoverflow für andere Alternativen zur Dokumentation von C++ und Python Code zusammen im selben Projekt.

Verwandt

 * Quelldokumentation
 * FreeCAD API Internetseite