Opis
Wszystkie makra powinny być odpowiednio udokumentowane w taki sam sposób, jak dokumentowane są polecenia Gui.
Powinny mieć osobną stronę wiki oraz być wymienione w jednej z kategorii w Przepisach na makra.
Strona Przepisy na makra zawiera dobry wybór makr stworzonych przez doświadczonych użytkowników, a wiele z nich można bezpośrednio zainstalować z poziomu Menedżera dodatków.
Zobacz model GuiCommand oraz strony makr takie jak Makro Loft i Makro Site From Contours, aby zobaczyć, jak powinny być dokumentowane makra. Powinny zawierać przynajmniej dwie sekcje: sekcję Opis z ogólnymi informacjami o użytkowaniu oraz sekcję Skrypt z właściwym kodem makra. Można dołączyć także inne sekcje według potrzeby, by dokładniej wyjaśnić sposób użycia makra.
Jeśli makro zapewnia dobrze zdefiniowaną funkcjonalność i jest dobrze udokumentowane, może zostać ostatecznie włączone jako część nowego lub istniejącego środowiska pracy.
Strona nowego makra
Oryginalna strona musi być napisana w języku angielskim. Po oznaczeniu jej do tłumaczenia przez jednego z administratorów, może zostać przetłumaczona na inny język.
Utwórz nową stronę dla makra, zaczynając nazwę od słowa Macro_, a następnie dodaj nazwę makra, na przykład Macro_Excellent_Modification.
Aby utworzyć link do strony, użyj: [[Macro_Excellent_Modification|Macro Excellent Modification]].
Na nowej stronie powinieneś użyć Template:Macro na samej górze, zawierającego minimum informacji:
{{Macro
|Name=Macro Excellent Modification
|Description=This macro does excellent things on existing shapes
|Author=your username
|Date=2018-11-30
}}
Możesz dodać niestandardową ikonę, jeśli nie ma takiej samej nazwy jak makro; możesz również dodać inne pola informacji.
{{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|Macro Regular Modification]]
}}
Podczas tłumaczenia strony używaj szablonu z lokalizacją. Należy podać nazwę szablonu wraz z dwuliterowym kodem języka (np. /fr, /it, /de) oraz bezpośrednio wskazać ikonę.
{{Macro/fr
|Name=Macro Excellent Modification translated
|Icon=Macro_Excellent_Modification.svg
|Description=(Translated description)
|Author=your username
|Date=2018-11-30
}}
lub użyj pola Translate.
{{Macro/fr
|Name=Macro Excellent Modification
|Translate=Macro Excellent Modification translated
|Description=(Translated description)
|Author=your username
|Date=2018-11-30
}}
- Użyj Special:Upload do przesłania niestandardowej ikony w formatach SVG lub PNG. Ikona powinna mieć taką samą nazwę jak makro.
- W przeciwnym razie domyślnie używane
Icon=Text-x-python.svg
. - Dla makr używanych w konsoli Pythona FreeCAD użyj
Icon=Text_console_python.png
. - Dla przykładowego makra wideo użyj szkieletu ikony
, uzupełnij ekran, aby uzyskać np. 
i zapisz nową ikonę pod tą samą nazwą co makro.
Template:Macro umieszcza informacje o używaniu i instalacji makr na każdej stronie.
Linki do Jak instalować makra oraz dostosowanie paski narzędzi w infoboksie na każdej stronie makra
Dodawanie dokumentacji makra
- Podobnie jak w przypadku polecenia Gui, wyjaśnij, co robi makro, jakie ma dane wejściowe, wyjściowe, opcje oraz ewentualne ograniczenia.
- Dodaj spersonalizowaną ikonę w formacie SVG lub PNG, aby inni użytkownicy mogli umieścić makro na własnym pasku narzędzi.
- Dołącz jedną lub więcej ilustracji, które wyjaśnią sposób użycia narzędzia.
- Jeśli makro wykonuje złożone zadanie, rozważ dodanie animowanego GIF-a prezentującego jego działanie. Maksymalny rozmiar GIF-a to 500 x 500 pikseli; większe mogą nie działać poprawnie. Nie zmieniaj rozmiaru GIF-a, ponieważ wiki nie odtwarza przeskalowanych animacji.
- Wspomnij o powiązanych makrach i środowiskach pracy, które uzupełniają funkcjonalność tego narzędzia.
- Podaj wersję FreeCAD, w której makro zostało stworzone. Informację tę można uzyskać z Pomoc → O programie FreeCAD → Kopiuj do schowka.
- Gdy te informacje są wklejone, wyglądają następująco
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)
Rozważ dodanie tych informacji w bloku komentarza wewnątrz kodu makra.
Dodawanie kodu makra
W sekcji Skrypt użyj Template:MacroCode, aby umieścić kod makra na stronie. Utworzy to blok tekstu w czcionce o stałej szerokości, co zachowa wcięcia niezbędne dla Pythona.
Jeśli blok kodu zawiera znaki {{ }} (podwójne nawiasy klamrowe zamykające i otwierające) lub | (pionowy pasek) to tagi <nowiki> ... </nowiki> można dodać bezpośrednio, aby umożliwić wyświetlanie tych specjalnych symboli.
Ten Template:MacroCode zasadniczo generuje blok tagów HTML <pre> ... </pre>, więc można ich użyć bezpośrednio zamiast używania szablonu. Menedżer dodatków będzie szukał największego takiego bloku i użyje go do treści makra.
{{MacroCode|code=
«Your code should be here»
}}
Lub jeśli zawiera znak pionową kreskę |.
{{MacroCode|code=
<nowiki>
«Your code should be here»
</nowiki>
}}
Lub
<pre> «Your code should be here» </pre>
Dodaj informacje nagłówkowe przed właściwym kodem.
__Title__="Title_Of_macro"
__Author__ = "User_Name"
__Version__ = "00.11"
__Date__ = "2015-07-25"
__Comment__ = "This is the comment of the macro"
__Web__ = "https://forum.freecad.org/viewtopic.php?f=3&t=7384"
__Wiki__ = "https://wiki.freecad.org/index.php?title=Macro_Title_Of_macro"
__Icon__ = "/usr/lib/freecad/Mod/plugins/icons/Title_Of_macro"
__IconW__ = "C:/Users/YourUserName/AppData/Roaming/FreeCAD"
__Help__ = "start the macro and follow the instructions"
__Status__ = "stable"
__Requires__ = "freecad 0.14.3706"
__Communication__ = "https://wiki.freecad.org/index.php?title=User:User_Name"
«Your code should be here»
Począwszy od wersji FreeCAD 0.17, te informacje są wykorzystywane przez Menedżera dodatków, który pobiera makro z repozytorium FreeCAD-macros.
Dodawania kodu makra poza wiki
Jeśli Twoje makro jest zbyt duże i przekracza 64 KB, nie będzie mogło być umieszczone na wiki. W takim przypadku użyj Template:Codeextralink z linkiem do bezpośredniego adresu internetowego z kodem.
Dla przykładu:
{{Codeextralink|https://gist.githubusercontent.com/mario52a/8d40ab6c018c2bde678f/raw/e16ad9ea7b38c0c47e42aa3019be01dd1267a620/FCInfo_en_Ver_1-20_Docked.FCMacro}}
Będzie to wyświetlane jako:
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")
Ten szablon musi być umieszczony na początku strony makra, w sekcji Opis. Powinien być to pierwszy blok kodu na stronie, aby Menedżer dodatków 
mógł go automatycznie wykryć i zaimportować. Zobacz przykład użycia na stronie Makro CirclePlus.
Dodawanie nowego makra do repozytorium wiki
Użyj Template:MacroLink, aby dodać wpis w odpowiedniej kategorii na stronie Przepisy na makra; w razie potrzeby utwórz nową kategorię.
* {{MacroLink|Macro_Excellent_Modification|Macro Excellent Modification}}: the macro described in a short sentence.
- Pierwszy argument to nazwa strony makra na wiki.
- Drugi argument to wyświetlany tekst, który może różnić się od nazwy strony. Utworzy to link do pierwszego argumentu, pokazując jako tekst drugi argument.
- Po dwukropku podaj krótki opis makra.
Możesz również użyć opcjonalnego parametru Icon=, aby określić plik obrazu, który zostanie umieszczony na początku linii. Ikona powinna być w formacie SVG lub PNG i mieć taką samą nazwę jak Twoje makro. Jeśli ten parametr nie zostanie podany, używana będzie domyślna ikona dla skryptu Pythona 24px.
* {{MacroLink|Icon=Macro_Excellent_Modification.svg|Macro_Excellent_Modification|Macro Excellent Modification}}: the macro described in a short sentence.
Aby zlokalizować ten szablon, użyj odpowiedniego linku językowego w pierwszym argumencie.
* {{MacroLink|Macro_Excellent_Modification/fr|Macro Excellent Modification}}: (translated description)
Dodawanie nowego makra do głównego repozytorium
Aby makro mogło być instalowane z poziomu Menedżera dodatków, powinno być umieszczone w centralnym repozytorium FreeCAD-macros.
Aby makro mogło zostać tam uwzględnione, najpierw musi zostać ocenione przez społeczność FreeCAD na forum w podforum Python scripting and macros. Po pozytywnej ocenie repozytorium FreeCAD-macros powinno zostać rozwidlone, nowe makro dodane do odpowiedniej gałęzi, a następnie ta gałąź wypchnięta i scalona z repozytorium głównym.
Ta strona pochodzi z https://wiki.freecad.org/Macro_documentation