Macro documentation/de

Beschreibung
Alle Makros sollten ordentlich dokumentiert werden, und zwar auf die gleiche Weise wie GUI-Befehle dokumentiert werden.

Sie sollten eine eigene Wiki-Seite haben und in einer der Kategorien unter Makro-Rezepte aufgeführt sein.

Die Seite Makro Rezepte enthält eine gute Auswahl von Makros, die von erfahrenen Benutzern erstellt wurden, und viele von ihnen können direkt mit dem Addon-Manager installiert werden.

Siehe GuiBefehl Modell und Makroseiten wie Makro Ausformung und Makro Bereich aus Konturen, um zu sehen, wie Makros dokumentiert werden sollten. Es sollten mindestens zwei Abschnitte enthalten sein, ein Abschnitt (Description) mit allgemeinen Informationen zur Verwendung und ein Abschnitt, der den eigentlichen Makrocode enthält. Bei Bedarf können weitere Abschnitte hinzugefügt werden, um die Verwendung des Makros näher zu erläutern.

Wenn ein Makro eine gut definierte Funktionalität bietet und gut dokumentiert ist, könnte es schließlich als Teil einer neuen oder eines bestehenden Arbeitsbereichs aufgenommen werden.



Neue Makroseite
Die Originalseite muss in Englisch geschrieben sein. Nachdem ein Administrator sie zur Übersetzung markiert hat, kann sie in andere Sprachen übersetzt werden.

Erstelle eine neue Seite für das Makro, die mit dem Wort beginnt, gefolgt von dem Namen des Makros, zum Beispiel. Um die Seite zu verknüpfen, verwendet man:.

Auf der neuen Seite solltest du oben Template:Macro verwenden, mit einem Minimum an Informationen:

Du kannst ein benutzerdefiniertes Symbol hinzufügen, wenn es nicht den gleichen Namen wie das Makro hat; du kannst auch andere Informationsfelder hinzufügen.

Wenn die Seite übersetzt wird, verwende eine lokalisierte Vorlage. Du musst den Namen mit dem aus zwei Buchstaben bestehenden Sprachcode angeben, und du musst das Symbol explizit angeben

oder verwende das Feld


 * Verwende Special:Upload, um das benutzerdefinierte Symbol in den SVG oder PNG Formaten hochzuladen. Es sollte den gleichen Namen wie das Makro haben.
 * Andernfalls wird es standardmäßig auf  [[Image:Text-x-python.svg|32px]] gesetzt.
 * Für das von FreeCAD in der Python Konsole verwendete Makro verwende  [[Image:Text_console_python.png|32px]].
 * Für das Beispielvideomakro verwende dieses Skelett des Symbols [[Image:Text_Video_Movie.png|32px]] und fülle den Bildschirm aus, um z.B. folgendes zu erhalten: [[Image:Macro_crank_simul.png|32px]] und speichern Sie  neue Symbol mit dem gleichen Namen desein Makros.

Template:Macro wird die Informationen zur Verwendung und Installation der Makros in jede Seite einfügen.





Hinzufügen der Makrodokumentation

 * Wie bei einem Gui Befehl, erkläre was das Makro tut, seine Eingänge, Ausgänge, Optionen und Begrenzungen, falls vorhanden.
 * Füge ein personalisiertes Symbol im Format SVG oder PNG für dein Makro ein, damit andere Benutzer es in eine benutzerdefinierte Werkzeugleiste einfügen können.
 * Füge ein oder mehrere Bilder hinzu, um die Verwendung deines Werkzeugs zu verdeutlichen.
 * Wenn das Makro eine komplexe Aufgabe erfüllt, solltest du in Erwägung ziehen, ein animiertes GIF hinzuzufügen, um seine Fähigkeiten zu demonstrieren. Das GIF Bild sollte eine maximale Größe von 500 x 500 Pixel haben; wenn das GIF größer ist, funktioniert die Animation möglicherweise nicht. Ändere die Größe des GIFs nicht, da das Wiki GIFs mit geänderter Größe nicht abspielen wird.
 * Erwähne verwandte Makros und Arbeitsbereiche, die die Funktion dieses Werkzeugs ergänzen.
 * Erwähne die Version von FreeCAD, die zur Erstellung des Makros verwendet wurde. Diese Informationen können unter entnommen werden.


 * Wenn diese Informationen eingefügt werden, sieht es folgendermaßen aus

Ziehe in Betracht, diese Informationen in einem Kommentarblock innerhalb des Codes des Makros hinzuzufügen.



Hinzufügen des Makrocodes
Innerhalb des Abschnitts  verwende Template:MacroCode, um den Code des Makros in der Seite zu platzieren. Dadurch wird ein Textblock erstellt, der die Monospace Schriftart verwendet, wodurch der für Python wichtige Weißraum erhalten bleibt.

Wenn der Codeblock die Zeichen  (doppelte schließende und öffnende Klammer) oder   (senkrechter Balken) enthält, können die    Markierungen explizit hinzugefügt werden, um die Anzeige dieser speziellen Symbole zu ermöglichen.

DieserTemplate:MacroCode erzeugt im Wesentlichen einen Block von HTML Markierungen, so dass diese direkt anstelle der Vorlagen verwendet werden können. Der Erweiterungsverwalter sucht nach dem größten solcher Blöcke und verwendet ihn für den Körper des Makros.

Oder wenn es den vertikalen Balken einschließt.

Oder

«Your code should be here»

Füge Kopfzeileninformationen vor deinem eigentlichen Code hinzu.

Beginnend mit FreeCAD 0.17 werden diese Informationen vom Erweiterungsverwalter verwendet, der das Makro aus dem FreeCAD-Makros Repositorium herunterlädt.



Hinzufügen von Makrocode außerhalb des Wikis
Wenn dein Makro zu groß ist, so dass es 64 KB überschreitet, kann es nicht im Wiki bereitgestellt werden. In diesem Fall verwende Template:Codeextralink mit einem Verweis auf die raw Web Adresse des Codes.

Zum Beispiel:

Es wird angezeigt als:

Diese Vorlage muss am Anfang der Makroseite im Abschnitt platziert werden. Es muss der erste Codeblock in der Seite sein, damit der  Addon-Manager sie automatisch erkennen und importieren kann. Siehe Makro CirclePlus für ein Anwendungsbeispiel.



Hinzufügen des neuen Makros zum Wiki Repositorium
Verwende Template:MacroLink, um eine Zeile in die entsprechende Kategorie in Makro-Rezepte einzuschließen; erstelle bei Bedarf eine neue Kategorie.


 * Das erste Argument ist der Name der Makroseite im Wiki.
 * Das zweite Argument ist der angezeigte Text, der sich vom Seitennamen unterscheiden kann. Dadurch wird ein Verweis auf das erste Argument erstellt, der das zweite Argument als Text anzeigt.
 * Nach dem Doppelpunkt folgt eine kurze Beschreibung des Makros.

Du kannst auch den optionalen Parameter  verwenden, um die Bilddatei anzugeben, die am Anfang der Zeile platziert wird. Das Symbol sollte eine SVG oder eine PNG Datei sein und den gleichen Namen wie dein Makro haben. Wenn dieser Parameter nicht angegeben wird, wird das Standardsymbol für ein Python Skript verwendet.

Um diese Vorlage zu lokalisieren, verwende den entsprechenden Sprachverweis im ersten Argument.



Hinzufügen des neuen Makros zum zentralen Repositorium
Um ein Makro aus dem Addon-Manager installierbar zu machen, sollte es in das zentrale FreeCAD-Makros -Repositorium aufgenommen werden.

Um das Makro dort aufzunehmen, muss es zunächst von der FreeCAD Gemeinschaft im Python scripting and macros Unterforum überprüft werden. Sobald dies geschehen ist, sollte das FreeCAD-Makro Repositorium abgezweigt werden, das neue Makro sollte in einen Zweig aufgenommen werden, und dann sollte der Zweig gepusht und in das Upstream- Repositorium zusammengeführt werden.