Documentation pour les macros

From FreeCAD Documentation
Jump to navigation Jump to search
This page is a translated version of the page Macro documentation and the translation is 100% complete.
Other languages:
English • ‎français • ‎italiano

Description

Toutes les macros doivent être correctement documentées de la même manière que les commandes Gui le sont. Elles doivent avoir une page wiki individuelle et être répertoriées dans l'une des catégories de Formules Macros.

La page formules macros contient une belle sélection de macros créées par des utilisateurs expérimentés, qui peuvent être installées directement à partir de l'utilitaire Addon Manager.

Voir le Modèle GuiCommand et les pages de macros comme les Macro Loft et Macro Site From Contours pour voir comment documenter les macros. Au moins deux sections doivent être incluses, une section Description avec des informations générales sur l’utilisation et une section Script pour contenir le code réel de la macro. D'autres sections peuvent être incluses si nécessaire pour expliquer plus en détail l'utilisation de la macro.

Si une macro fournit une fonctionnalité bien définie et est bien documentée, elle pourrait éventuellement être incluse dans un atelier nouveau ou déjà existant.

Page nouvelle macro

Créez une nouvelle page pour la macro commençant par le mot Macro_, par exemple, Macro_Excellent_Modification. Le lien peut être utilisé sans trait de soulignement sous la forme [[Macro Excellent Modification|Excellente Modification de Macro]], ce qui s'affiche Excellente Modification de Macro ; les espaces sont automatiquement convertis en traits de soulignement.

Dans la nouvelle page, vous devez utiliser le Template:Macro/fr en haut, avec un minimum d'informations :

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

Vous pouvez ajouter une icône personnalisée si elle ne porte pas le même nom que la macro ; vous pouvez également ajouter d'autres champs d'information.

{{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]]
}}

Lors de la traduction de la page, utilisez un modèle localisé. Vous devez spécifier le nom avec le code de langue à deux lettres (/fr, /it, /de), et vous devez indiquer l'icône explicitement

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

ou utilisez le champ Translate

{{Macro/fr
|Name=Macro Excellent Modification
|Translate=Macro Excellent Modification translated
|Description=(Translated description)
|Author=your username
|Date=2018-11-30
}}
  • Utilisez la page Special:Upload pour télécharger votre icône personnalisée aux formats SVG ou PNG. Elle devrait avoir le même nom que la macro.
  • Sinon, l'icône Icon=Text-x-python.svg Text-x-python.svg par défaut sera utilisée.
  • Pour les macros utilisée en ligne de commande dans la console Python de FreeCAD utilisez Icon=Text_console_python.png Text console python.png.
  • pour les exemples de vidéo, utilisez ce squelette d'icône Text Video Movie.png et remplissez le pour obtenir ex: Macro crank simul.png et sauvez le avec le même nom que votre macro.

Template:Macro mettra les informations sur l'utilisation et l'installation des macros dans chaque page.

Macro Recipes MacroHowToInstall.png

Les liens Comment installer une macro et créer une barre d'outils se trouvent dans l'infobox de chaque page de macro


Ajouter la documentation sur la macro

  • Tout comme une Gui Command, expliquez ce que fait la macro, ses entrées, sorties, options et limitations, etc.
  • Inclure une icône personnalisée au format SVG ou PNG pour votre macro afin que les autres utilisateurs puissent l’inclure dans une barre d’outils personnalisée.
  • Ajoutez une ou plusieurs images pour clarifier l'utilisation de votre outil.
  • Si la macro effectue une tâche complexe, envisagez d'ajouter un fichier GIF animé pour présenter ses fonctionnalités. L'image GIF doit avoir une taille maximale de 500 x 500 pixels ; si le GIF est plus grand, l'animation peut ne pas fonctionner. Ne redimensionnez pas le GIF car le wiki ne lira pas les GIF redimensionnés.
  • Mentionnez les macros et les ateliers associés qui complètent la fonction de cet outil.
  • Mentionnez la version de FreeCAD utilisée pour créer la macro. Ces informations peuvent être recueillies à partir de Aide → À propos de FreeCAD → Copier dans le presse-papiers.
Lorsque cette information est collée, elle ressemble à ceci
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)

Envisagez d'ajouter ces informations dans un bloc de commentaires à l'intérieur du code de la macro.

Ajouter une nouvelle macro

Dans la section Script, utilisez Template:MacroCode pour placer le code de la macro dans la page. Cela créera un bloc de texte utilisant la police de caractères monospace, qui préservera les espaces essentiels pour Python.

Si le bloc de code contient les caractères {{ }} (double accolade fermante et accolade ouvrante) ou | (barre verticale), les balises <nowiki> ... </nowiki> peuvent être ajoutées explicitement pour permettre l'affichage de ces symboles spéciaux.

Ce Template:MacroCode génère essentiellement un bloc de balises HTML <pre> ... </pre> de sorte que celles-ci peuvent être utilisées directement au lieu d'utiliser le modèle. Le Gestionnaire d'Addon recherchera le plus gros bloc de ce type et l'utilisera pour le corps de la macro.

{{MacroCode|code=

«Your code should be here»

}}

Ou si elle comprend la barre verticale |.

{{MacroCode|code=
<nowiki>

«Your code should be here»

</nowiki>
}}

Ou

<pre>

«Your code should be here»

</pre>

Ajouter les informations d'en-tête avant votre code réel.

{{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»
}}

À partir de FreeCAD 0.17, ces informations sont utilisées par le Gestionnaire d'Addon qui télécharge la macro à partir de FreeCAD-macros.

Ajouter le code d'une macro en dehors du wiki

Si votre macro est trop grosse et dépasse 64 Ko, elle ne pourra pas être hébergée sur le wiki. Dans ce cas, utilisez le Template:Codeextralink avec un lien vers l'adresse Web de la page du code brut (page texte du code).

Exemple :

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

Ce qui sera affiché comme :

Temporary code for external macro link. Do not use this code. This code is used exclusively by Addon Manager.


# 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")
<class="rawcodeurl"><a href="https://gist.githubusercontent.com/mario52a/8d40ab6c018c2bde678f/raw/e16ad9ea7b38c0c47e42aa3019be01dd1267a620/FCInfo_en_Ver_1-20_Docked.FCMacro">raw code</a>


Ce modèle doit être placé au début de la page de macro, dans la section Description. Il doit s'agir du premier bloc de code de la page pour que l'Addon Manager AddonManager.svg puisse le détecter automatiquement et l'importer. Voir Macro CirclePlus pour un exemple d'utilisation.

PS : En cas de mise à jour dans GitHub le chemin du code brut est modifié, ne pas oublier de modifier le lien dans le modèle Codeextralink.

Ajouter une nouvelle macro au référentiel wiki

Utilisez le template Template:MacroLink pour inclure une ligne dans la catégorie appropriée de Formules Macros ; créer une nouvelle catégorie si nécessaire.

* {{MacroLink|Macro_Excellent_Modification|Macro Excellent Modification}}: the macro described in a short sentence.
  • Le premier argument est le nom de la macro page dans le wiki.
  • Le deuxième argument est le texte affiché, qui peut être différent du nom de la page. Cela créera un lien vers le premier argument, montrant le deuxième argument comme texte.
  • Une courte description de la macro vient après les deux points.

Vous pouvez également utiliser le paramètre facultatif Icon= pour spécifier le fichier image qui sera placé au début de la ligne. L'icône doit être un fichier SVG ou PNG, et doit porter le même nom que votre macro. Si ce paramètre n'est pas spécifié, l'icône par défaut Text-x-python.svg sera utilisée pour le script Python.

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

Pour localiser ce modèle, utilisez le lien de langue approprié dans le premier argument.

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

Ajouter une nouvelle macro au référentiel central

Pour rendre une macro installable à partir de l'Addon Manager, elle doit être incluse dans le référentiel central FreeCAD-macros.

Pour y inclure la macro, elle doit d’abord être examinée par la communauté FreeCAD du sous-forum Python scripting and macros. Une fois que cela est fait, le reférentiel FreeCAD-macros doit être divisé, la nouvelle macro doit être incluse dans une branche, puis la branche doit être poussée et fusionnée dans le référentiel en amont.