Macro documentation/fr

Description
Toutes les macros doivent être correctement documentées de la même manière que les commandes Gui le sont.

Elles doivent avoir leur propre page wiki et être répertoriées dans l'une des catégories de la Liste des Macros.

La page Liste des Macros contient une sélection de macros créées par des utilisateurs expérimentés, qui peuvent être installées directement à partir du Gestionnaire des extensions.

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 avec des informations générales sur l’utilisation et une section  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.



Nouvelle page pour une macro
Créez une nouvelle page pour la macro en commençant par le mot puis le nom de la macro, par exemple,. Le lien peut être utilisé sans trait de soulignement sous la forme, ce qui s'affiche Macro Excellent Modification. Les espaces sont automatiquement convertis en traits de soulignement.

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

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.

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 et vous devez indiquer l'icône explicitement

ou utilisez le champ


 * 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  [[Image:Text-x-python.svg|32px]] par défaut sera utilisée.
 * Pour les macros utilisée en ligne de commande dans la console Python de FreeCAD utilisez  [[Image:Text_console_python.png|32px]].
 * pour les exemples de vidéo, utilisez ce squelette d'icône [[Image:Text_Video_Movie.png|32px]] et remplissez le pour obtenir ex: [[Image:Macro_crank_simul.png|32px]] 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.





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.


 * Lorsque cette information est collée, elle ressemble à ceci

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



Ajouter le code de la macro
Dans la section, 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   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  de sorte que celles-ci peuvent être utilisées directement au lieu d'utiliser le modèle. Le Gestionnaire des extensions recherchera le plus gros bloc de ce type et l'utilisera pour le corps de la macro.

Ou si elle comprend la barre verticale.

Ou

«Your code should be here»

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

À partir de FreeCAD 0.17, ces informations sont utilisées par le Gestionnaire des extensions qui télécharge la macro à partir du dépôt 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 :

Ce qui sera affiché comme :

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



Ajouter une nouvelle macro au dépôt du wiki
Utilisez le template Template:MacroLink pour inclure une ligne dans la catégorie appropriée de la Liste des Macros. Créez une nouvelle catégorie si nécessaire.


 * 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  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 sera utilisée pour le script Python.

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



Ajouter une nouvelle macro au dépôt central
Pour rendre une macro installable à partir du Gestionnaire des extensions, elle doit être incluse dans le dépôt 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 dépôt des 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 dépôt en amont.