Makrodokumentation

From FreeCAD Documentation
Revision as of 22:24, 10 November 2020 by Maker (talk | contribs) (Created page with "Diese Vorlage muss am Anfang der Makroseite im Abschnitt {{Emphasis|Beschreibung}} platziert werden. Es muss der erste Codeblock in der Seite sein, damit der Addon Manager/d...")

Beschreibung

Alle Makros sollten ordnungsgemäß 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 Makro Rezepte Seite hat eine gute Auswahl von Makros, die von erfahrenen Benutzern erstellt wurden, und viele von ihnen können direkt aus dem Erweiterungsverwalter installiert werden.

Siehe GuiBefehl Modell und Makroseiten wie Makro Ausfromung und Makro Seite 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 Script, 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

Erstelle eine neue Seite für das Makro, die mit dem Wort Macro_ beginnt, zum Beispiel Macro_Excellent_Modification. Der Verweis kann ohne Unterstriche als [[Macro Excellent Modification/de|Makro Excellent Modification]] verwendet werden, was zu Makro Ausgezeichnete Änderung führt; die Leerzeichen werden automatisch in Unterstriche umgewandelt.

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

{{Macro
|Name=Macro Excellent Modification
|Description=This macro does excellent things on existing shapes
|Author=your username
|Date=2018-11-30
}}

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

{{Macro
|Name=Macro Excellent Modification
|Icon=Macro_custom_icon.svg
|Description=This macro does excellent things on existing shapes
|Author=your username
|Date=2018-11-30
|Version=3.14516
|SeeAlso=[[Macro Regular Modification]]
}}

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

{{Macro/fr
|Name=Macro Excellent Modification translated
|Icon=Macro_Excellent_Modification.svg
|Description=(Translated description)
|Author=your username
|Date=2018-11-30
}}

oder verwende das Translate Feld

{{Macro/fr
|Name=Macro Excellent Modification
|Translate=Macro Excellent Modification translated
|Description=(Translated description)
|Author=your username
|Date=2018-11-30
}}
  • Use Special:Upload to upload the custom icon in SVG or PNG formats. It should have the same name as the macro.
  • Otherwise it will default to Icon=Text-x-python.svg .
  • For the macro used in the Python console by FreeCAD use Icon=Text_console_python.png .
  • For the example video macro use this skeleton of the icon and fill the screen for obtain ex: and save the new icon with the same name of your macro.

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

Wie Makros installieren und Werkzeugleisten anpassen Verweise in der Infobox auf jeder Makroseite


Hinzufügen der Makrodokumentation

  • Just like a Gui Command, explain what the macro does, its inputs, outputs, options, and limitations, if any.
  • Include a personalized icon in SVG or PNG format for your macro so that other users can include it in a custom toolbar.
  • Add one or more images to clarify the usage of your tool.
  • If the macro performs a complex task, consider adding an animated GIF to showcase its capabilities. The GIF image should have a maximum size of 500 x 500 pixels; if the GIF is bigger, the animation may not work. Do not resize the GIF as the wiki will not play resized GIFs.
  • Mention related macros and workbenches that complement the function of this tool.
  • Mention the version of FreeCAD used to create the macro. This information can be gathered from Help → About FreeCAD → Copy to clipboard.
Wenn diese Informationen eingefügt werden, sieht es folgendermaßen aus
OS: Ubuntu 18.04.1 LTS
Word size of OS: 64-bit
Word size of FreeCAD: 64-bit
Version: 0.18.15302 (Git)
Build type: Release
Branch: master
Hash: 2e03d2f298677b8212c22cbbc3cb20b7c80eabb5
Python version: 2.7.15rc1
Qt version: 4.8.7
Coin version: 4.0.0a
OCC version: 7.3.0
Locale: English/UnitedStates (en_US)

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

Hinzufügen des Makrocodes

Inside the Script section, use Template:MacroCode to place the code of the macro in the page. This will create a block of text that uses monospace font, which will preserve the whitespace that is essential for Python.

If the block of code contains the characters {{ }} (double closing brace and opening brace) or | (vertical bar), the <nowiki> ... </nowiki> tags can be added explicitly to allow displaying these special symbols.

This Template:MacroCode essentially generates a block of HTML tags <pre> ... </pre>, so these can be used directly instead of using the template. The Addon Manager will search for the biggest such block and use it for the body of the macro.

{{MacroCode|code=

«Your code should be here»

}}

Or if it includes the vertical bar |.

{{MacroCode|code=
<nowiki>

«Your code should be here»

</nowiki>
}}

Oder

<pre>

«Your code should be here»

</pre>

Add header information before your actual code.

{{MacroCode|code=
__Title__="Title_Of_macro"
__Author__ = "User_Name"
__Version__ = "00.11"
__Date__    = "2015-07-25"
__Comment__ = "This is the comment of the macro"
__Web__ = "http://forum.freecadweb.org/viewtopic.php?f=3&t=7384"
__Wiki__ = "http://www.freecadweb.org/wiki/index.php?title=Macro_Title_Of_macro"
__Icon__  = "/usr/lib/freecad/Mod/plugins/icons/Title_Of_macro"
__IconW__  = "C:/Documents and Settings/YourUserName/Application Data/FreeCAD"
__Help__ = "start the macro and follow the instructions"
__Status__ = "stable"
__Requires__ = "freecad 0.14.3706"
__Communication__ = "http://www.freecadweb.org/wiki/index.php?title=User:User_Name" 

«Your code should be here»
}}

Starting with FreeCAD 0.17, this information is used by the Addon Manager, which downloads the macro from the FreeCAD-macros repository.

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:

{{Codeextralink|https://gist.githubusercontent.com/mario52a/8d40ab6c018c2bde678f/raw/e16ad9ea7b38c0c47e42aa3019be01dd1267a620/FCInfo_en_Ver_1-20_Docked.FCMacro}}

Es wird angezeigt als:

Temporary code for external macro link. Do not use this code. This code is used exclusively by Addon Manager. Link for optional manual installation: Macro


# This code is copied instead of the original macro code
# to guide the user to the online download page.
# Use it if the code of the macro is larger than 64 KB and cannot be included in the wiki
# or if the RAW code URL is somewhere else in the wiki.

from PySide import QtGui, QtCore

diag = QtGui.QMessageBox(QtGui.QMessageBox.Information,
    "Information",
    "This macro must be downloaded from this link\n"
    "\n"
    "https://gist.githubusercontent.com/mario52a/8d40ab6c018c2bde678f/raw/e16ad9ea7b38c0c47e42aa3019be01dd1267a620/FCInfo_en_Ver_1-20_Docked.FCMacro" + "\n"
    "\n"
    "Quit this window to access the download page")

diag.setWindowFlags(QtCore.Qt.WindowStaysOnTopHint)
diag.setWindowModality(QtCore.Qt.ApplicationModal)
diag.exec_()

import webbrowser 
webbrowser.open("https://gist.githubusercontent.com/mario52a/8d40ab6c018c2bde678f/raw/e16ad9ea7b38c0c47e42aa3019be01dd1267a620/FCInfo_en_Ver_1-20_Docked.FCMacro")


Diese Vorlage muss am Anfang der Makroseite im Abschnitt Beschreibung platziert werden. Es muss der erste Codeblock in der Seite sein, damit der Erweiterungsverwalter kann sie automatisch erkennen und importieren. Siehe Makro KreisPlus für ein Verwendungsbeispiel.

PS: Im Falle einer Aktualisierung in GitHub wird der Pfad des RAW Codes geändert, nicht vergessen, den Verweis in der Codeextralink Vorlage zu ändern.

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.

* {{MacroLink|Macro_Excellent_Modification|Macro Excellent Modification}}: the macro described in a short sentence.
  • 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 Icon= 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.

* {{MacroLink|Icon=Macro_Excellent_Modification.svg|Macro_Excellent_Modification|Macro Excellent Modification}}: the macro described in a short sentence.

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

* {{MacroLink|Macro_Excellent_Modification/fr|Macro Excellent Modification}}: (translated description)

Hinzufügen des neuen Makros zum zentralen Repositorium

Um ein Makro aus dem Erweiterungsverwalter 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.