Macro documentation/pl

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.

PS: W przypadku aktualizacji na GitHub, gdy ścieżka do surowego kodu zostanie zmieniona, nie zapomnij zaktualizować linku w szablonie Codeextralink.

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.