Source documentation/de

Other languages:
Zusätzliche Python-Module
Mitwirkende
Index

Übersicht

Der FreeCAD-Quellcode enthält Kommentare, die ermöglichen, die Dokumentation der Programmierung automatisch mit Doxygen, einem beliebten Quellcode-Dokumentationssystem, zu erstellen. Doxygen kann sowohl die C++ als auch die Python-Anteile von FreeCAD dokumentieren; als Ergebnis werden HTML-Seiten erstellt, mit Hyperlinks zu allen dokumentierten Funktionen und Klassen.

Die Dokumentation steht online auf der Website der FreeCAD-API zur Verfügung. Bitte beachten, dass diese Dokumentation möglicherweise nicht immer auf dem neuesten Stand ist. Werden weitere Einzelheiten benötigt, kann der aktuellste FreeCAD-Quellcode heruntergeladen und die Dokumentation selbst erstellt werden. Wenn sich dringende Fragen zum Code ergeben, können diese im Entwicklerbereich des FreeCAD-Forums gestellt werden.

Das Kompilieren der API-Dokumentation folgt den gleichen allgemeinen Schritten wie das Kompilieren der ausführbaren FreeCAD-Datei, wie auf der Seite Kompilieren unter Linux angegeben.

Allgemeiner Arbeitsablauf zum Erstellen der Dokumentation der Programmierung von FreeCAD. Die Pakete Doxygen und Graphviz müssen sich im System befinden, ebenso wie der FreeCAD-Quellcode selbst. CMake konfiguriert das System so, dass mit einer einzigen make-Anweisung die Dokumentation für das gesamte Projekt in viele HTML-Dateien mit Diagrammen übersetzt wird.

Quelldokumentation erstellen

Komplette Dokumentation

Ist Doxygen installiert, ist es sehr einfach, die Dokumentation zu erstellen. Wird auch Graphviz installiert, können auch Diagramme erstellt werden, die die Beziehungen zwischen verschiedenen Klassen und Bibliotheken im FreeCAD-Code darstellen. Graphviz wird auch von FreeCADs Abhängigkeitsdiagramm verwendet, um die Beziehungen zwischen verschiedenen Objekten anzuzeigen. 

sudo apt install doxygen graphviz

Dann den gleichen Schritten folgen, die beim Kompilieren von FreeCAD durchzuführen wären, die auf der Seite Kompilieren unter Linux beschrieben, und hier aus Gründen der Übersichtlichkeit zusammengefasst sind. 

git clone https://github.com/FreeCAD/FreeCAD.git freecad-source
mkdir freecad-build
cd freecad-build
cmake -DBUILD_QT5=ON -DPYTHON_EXECUTABLE=/usr/bin/python3 ../freecad-source

Ins Build-Verzeichnis wechseln und die folgende Anweisung ausgeben, um nur die Dokumentation zu erstellen. 

make -j$(nproc --ignore=2) DevDoc

Wie unter Kompilieren (Beschleunigen) erwähnt, legt die Option -j die Anzahl der CPU-Kerne fest, die für das Kompilieren verwendet werden. Die resultierenden Dokumentationsdateien erscheinen in dem Verzeichnis 

freecad-build/doc/SourceDocu/html/

Der Einstiegspunkt in die Dokumentation ist die Datei index.html, die mit einem Webbrowser geöffnet werden kann: 

xdg-open freecad-build/doc/SourceDocu/html/index.html

Das Ziel DevDoc erzeugt eine beträchtliche Datenmenge, etwa 5 GB neue Dateien, insbesondere aufgrund der von Graphviz erstellten Diagramme.

Gekürzte Dokumentation

Die komplette Dokumentation belegt etwa 3 GB Speicherplatz auf der Festplatte. Eine alternative, kleinere Version der Dokumentation, die nur ca. 600 MB benötigt, kann mit einem anderen Ziel erstellt werden. Dies ist die Version, die auf der Webseite FreeCAD-API angezeigt wird. 

make -j$(nproc --ignore=2) WebDoc

Die Doumentation auf der Webseite FreeCAD-API wird automatisch aus der Seite https://github.com/FreeCAD/SourceDoc erstellt. Jeder kann diese nachbauen und einen Pull-Request einreichen: 

git clone https://github.com/FreeCAD/FreeCAD
cd FreeCAD
mkdir build
cd build
mkdir -p doc/SourceDocu/html
cd doc/SourceDocu/html
git clone your-fork-url
cd ../../..
cmake -DBUILD_QT5=ON -DPYTHON_EXECUTABLE=/usr/bin/python3 ..
make WebDoc
cd doc/SourceDocu/html
git commit
git push

Andere Versionen

FreeCAD 0.19 development Dokumentation erstellt von qingfeng.xia.

Coin3D-Dokumentation integrieren

Auf Unix-Systemen ist es möglich, die Coin3D-Quelldokumentation mit der von FreeCAD zu verknüpfen. Dies ermöglicht eine einfachere Navigation und vollständige Vererbungsdiagramme für aus Coin abgeleitete Klassen.

Wird das Dokumentationspaket für Coin nicht installiert, werden die Verknüpfungen erstellt, mit denen auf die Online-Dokumentation unter BitBucket zugegriffen werden kann. Dies geschieht, wenn eine Doxygen-Tag-Datei während der Konfiguration mit wget heruntergeladen werden kann.

Doxygen verwenden

Auf der Seite Doxygen gibt es eine ausführliche Erklärung, wie man C++- und Python-Quellcode kommentiert, damit er von Doxygen zur automatischen Erstellung der Dokumentation verarbeitet werden kann.

Im Wesentlichen muss vor jeder Klassen- oder Funktionsdefinition ein Kommentarblock, beginnend mit /** oder /// für C++ oder ## für Python, erscheinen, damit er von Doxygen aufgenommen wird. Viele spezielle Befehle, die mit \ oder @ beginnen, können verwendet werden, um Teile des Codes zu definieren und die Ausgabe zu formatieren. Auch Markdown-Syntax wird innerhalb des Kommentarblocks verstanden, was erleichtert, bestimmte Teile der Dokumentation hervorzuheben. 

/**
 * Returns the name of the workbench object.
 */
std::string name() const;

/**
 * Set the name to the workbench object.
 */
void setName(const std::string&);

/// remove the added TaskWatcher
void removeTaskWatcher(void);


Zusätzliche Python-Module
Mitwirkende
Index
Anwenderdokumentation