Donate

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.

• Den Quellcode von FreeCAD laden und in ein eigenes Verzeichnis freecad-source ablegen.
• Ein weiteres Verzeichnis freecad-build erstellen, in dem FreeCAD und seine Dokumentation zusammengestellt wird.
• Die Quellen mit cmake konfigurieren und dabei sicherstellen, dass das Quellverzeichnis und die erforderlichen Optionen für diese Zusammenstellung angegeben werden.
• Das Erstellen der Dokumentation mit make auslösen.

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:

• Eine Verzweigung (Fork) des Datenspeichers unter https://github.com/FreeCAD/SourceDoc erstellen.
• Auf dem eigenen Rechner: Den FreeCAD-Code klonen (wenn noch nicht geschehen), Ein Verzeichnis für die Zusammenstellung der Dokumentation erstellen und das obige Verzeichnis SourceDoc darin klonen. SourceDoc wird aktualisiert, wenn die Dokumentation neu erstellt wird und es kann hinterher ein commit & push der Ergebnisse erfolgen:

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

• Online zum eigenen Zweig wechseln und einen Pull-Request erstellen.

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.

• libcoin-doc, libcoin80-doc, oder ein ähnlich benanntes Paket installieren.
• Das Archiv coin.tar.gz entpacken, das sich unter /usr/share/doc/libcoin-doc/html befindet; die Dateien sind möglicherweise bereits auf deinem System entpackt.
• Die Quelldokumentation erneut erstellen.

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