Macro documentation/it

Descrizione

Tutte le macro devono essere documentate correttamente, nello stesso modo con cui vengono documentati i comandi GUI.

Dovrebbero avere una pagina wiki individuale e dovrebbero essere elencate in una delle categorie nella Raccolta di macro.

La pagina della Raccolta di macro contiene una buona selezione di macro create da utenti esperti e molte di esse possono essere installate direttamente da Addon Manager.

Consultare modello GuiCommand e pagine macro come Macro Loft e Macro Site From Contours per informazioni su come documentare le macro. È necessario includere almeno due sezioni: una sezione Descrizione con informazioni generali sull'utilizzo e una sezione Script per contenere il codice macro vero e proprio. È possibile includere altre sezioni, se necessario, per spiegare in modo più dettagliato l'utilizzo della macro.

Se una macro fornisce una funzionalità ben definita ed è ben documentata, potrebbe essere inclusa in futuro come parte di un ambiente di lavoro nuovo o esistente.

Pagina nuova macro

La pagina originale deve essere scritta in inglese. Dopo che uno degli amministratori l'avrà contrassegnata per la traduzione, potrà essere tradotta in un'altra lingua.

Creare una nuova pagina per la macro iniziando con la parola Macro_ seguita dal nome della macro, ad esempio Macro_Excellent_Modification. Per creare un collegamento alla pagina, usare: [[Macro_Excellent_Modification|Macro Excellent Modification]].

Nella nuova pagina si dovrebbe usare Template:Macro in alto (dopo <languages/> and <translate> tags), con un minimo di informazioni:

<languages/>
<translate>

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

==Description==
text ....
text ....

</translate>
do not translate (ex: image ... video ... code ...)
<translate>

==Use==
text ....
text ....

</translate>

È possibile aggiungere un'icona personalizzata se non ha lo stesso nome della macro; è anche possibile aggiungere altri campi di informazioni.

{{Macro
|Name=Macro Excellent Modification
|Icon="https://wiki.freecad.org/images/d/d5/Macro_Align_Face_Object_to_View.png" # path of the icon
|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]]
}}

Quando si traduce la pagina, usare un modello localizzato. Si deve specificare il nome con il codice della lingua a due lettere (/fr, /it, /de) e indicare esplicitamente l'icona.

{{Macro/fr
|Name=Macro Excellent Modification translated
|Icon="https://wiki.freecad.org/images/d/d5/Macro_Align_Face_Object_to_View.png" # path of the icon
|Description=(Translated description)
|Author=your username
|Date=2018-11-30
}}

oppure usare il campo Translate

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

Usare Special:Upload per caricare l'icona personalizzata in formato SVG o PNG. Deve avere lo stesso nome della macro.
In caso contrario, verrà utilizzata l'icona predefinita Icon=Text-x-python.svg .
Per la macro utilizzata nella console Python di FreeCAD, usare Icon=Text_console_python.png .
Per la macro video di esempio, usare questa base per l'icona , riempire lo schermo per ottenere, ad esempio, e salvare la nuova icona con lo stesso nome della macro.

Template:Macro inserirà in ogni pagina le informazioni sull'uso e sull'installazione delle macro.

Link a Come installare le macro e Personalizzare le barre degli strumenti nell'infobox di ogni pagina dedicata a una macro

Aggiunta della documentazione della macro

Proprio come per un comando GUI, spiegare cosa fa la macro, nonché i suoi input, output, opzioni e limitazioni (se presenti).
Includere un'icona personalizzata in formato SVG o PNG per la macro, in modo che altri utenti possano inserirla in una barra degli strumenti personalizzata.
Aggiungere una o più immagini per chiarire l'utilizzo dello strumento.
Se la macro esegue un'operazione complessa, valutare l'aggiunta di una GIF animata per mostrarne le funzionalità. L'immagine GIF deve avere una dimensione massima di 500 x 500 pixel; se la GIF è più grande, l'animazione potrebbe non funzionare. Non ridimensionare la GIF, poiché la wiki non riproduce GIF ridimensionate.
Indicare le macro e gli ambienti di lavoro (workbench) correlati che integrano le funzionalità di questo strumento.
Specificare la versione di FreeCAD utilizzata per creare la macro. Queste informazioni possono essere recuperate tramite Aiuto → Informazioni su FreeCAD → Copia negli appunti.

Quando queste informazioni vengono incollate, appaiono così

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)

Si valuti di aggiungere queste informazioni in un blocco di commenti all'interno del codice della macro.

Aggiunta del codice della macro

All'interno della sezione Script, utilizzare Template:MacroCode per inserire il codice della macro nella pagina. Così si creerà un blocco di testo con carattere a spaziatura fissa (monospace), preservando gli spazi bianchi fondamentali per Python.

Se il blocco di codice contiene i caratteri {{ }} (doppia parentesi graffa di chiusura e di apertura) o | (barra verticale), è possibile aggiungere esplicitamente i tag <nowiki> ... </nowiki> per consentire la visualizzazione di questi simboli speciali.

Questo Template:MacroCode genera essenzialmente un blocco di tag HTML <pre> ... </pre>; pertanto, è possibile utilizzarli direttamente anziché ricorrere al template. Lo Addon Manager cercherà il blocco di questo tipo più grande e lo utilizzerà come corpo della macro.

{{MacroCode|code=

«Your code should be here»

}}

Oppure, se include la barra verticale |.

{{MacroCode|code=
<nowiki>

«Your code should be here»

</nowiki>
}}

Oppure

<pre>

«Your code should be here»

</pre>

Aggiungere le informazioni di intestazione prima del codice vero e proprio.

__Name__ = "Name Of macro"
__Comment__ = "This is the comment of the macro"
__Author__ = "User_Name"
__Version__ = "00.11"
__Date__ = "2015-07-25" # YYYY-MM-DD
__License__ = "LGPL-2.0-or-later as FreeCAD, MIT, CC0-1.0"    #  see https://spdx.org/licenses/
__Web__ = "https://forum.freecad.org/viewtopic.php?f=3&t=7384"
__Wiki__ = "https://wiki.freecad.org/index.php?title=Macro_Name_Of_macro"
__Icon__ = "https://wiki.freecad.org/images/d/d5/Macro_Align_Face_Object_to_View.png" # path of the icon
__Xpm__ = "(OPTIONAL)"
__Help__ = "start the macro and follow the instructions"
__Status__ = "Stable" # Alpha, Beta
__Requires__ = "FreeCAD >= 0.14.3706"
__Communication__ = "https://wiki.freecad.org/index.php?title=User:User_Name"
__Files__ = "List of files separed by comma"

«Your code should be here»

A partire da FreeCAD 0.17, queste informazioni vengono utilizzate dal Gestore degli Addon, che scarica la macro dal repository FreeCAD-macros.

Aggiunta di codice macro al di fuori della wiki

Se la macro supera i 64 KB di dimensione, non potrà essere ospitata sulla wiki. In tal caso, utilizzare Template:Codeextralink inserendo il link all'indirizzo web diretto del codice.

Per esempio:

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

Verrà visualizzato come:

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")

Questo modello deve essere inserito all'inizio della pagina della macro, nella sezione Description. Deve costituire il primo blocco di codice della pagina, affinché il Gestore dei componenti aggiuntivi possa rilevarlo e importarlo automaticamente. Vedere Macro CirclePlus per un esempio di utilizzo.

PS: In caso di aggiornamento su GitHub, se il percorso del codice RAW dovesse cambiare, non dimenticare di modificare il link nel template Codeextralink.

Aggiunta della nuova macro al repository della wiki

Utilizzare Template:MacroLink per inserire una voce nella categoria appropriata all'interno di Macros recipes; creare una nuova categoria se necessario.

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

Il primo argomento è il nome della pagina della macro nella wiki.
Il secondo argomento è il testo visualizzato, che può differire dal nome della pagina. Verrà creato un collegamento alla pagina indicata nel primo argomento, mostrando il secondo argomento come testo del link.
Dopo i due punti sopra segue una breve descrizione della macro.

È inoltre possibile utilizzare il parametro opzionale Icon= per specificare il file immagine da collocare all'inizio della riga. L'icona deve essere un file SVG o PNG e deve avere lo stesso nome della macro. Se questo parametro non viene specificato, verrà utilizzata l'icona predefinita per gli script Python .

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

Per localizzare questo template, utilizzare il link alla lingua appropriata nel primo argomento.

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

Aggiunta della nuova macro al repository centrale

Per rendere una macro installabile tramite il Gestore dei componenti aggiuntivi, è necessario includerla nel repository centrale FreeCAD-macros.

Per includervi la macro, è necessario prima sottoporla all'esame della comunità di FreeCAD nell'apposita sottosezione del forum dedicata a script Python e macro (Python scripting and macros). Una volta fatto ciò, occorre effettuare il fork del repository FreeCAD-macros, inserire la nuova macro in un branch, per poi eseguire il push e il merge del branch nel repository upstream.