Macro documentation: Difference between revisions

From FreeCAD Documentation
(→‎Description: as part of a new or an existing workbench.)
(Addon_Manager -> Std_AddonMgr)
(23 intermediate revisions by 4 users not shown)
Line 2: Line 2:
<translate>
<translate>


== Description ==
== Description == <!--T:1-->


<!--T:2-->
All macros should be properly documented in the same way [[Gui Command]]s are documented. They should have an individual wiki page, and should be listed in one of the categories in [[Macros recipes]].
All macros should be properly documented in the same way [[Gui Command|Gui Command]]s are documented. They should have an individual wiki page, and should be listed in one of the categories in [[Macros recipes|Macros recipes]].


<!--T:3-->
The [[Macros recipes]] page has a good selection of macros created by experienced users, and many of them can be directly installed from the [[Addon Manager]].
The [[Macros recipes|Macros recipes]] page has a good selection of macros created by experienced users, and many of them can be directly installed from the [[Std_AddonMgr|Addon Manager]].


<!--T:4-->
See [[GuiCommand model]] and macro pages like [[Macro Loft]] and [[Macro Site From Contours]] to see how macros should be documented. At least two sections should be included, a {{Emphasis|Description}} section with general usage information, and a {{Emphasis|Script}} section to hold the actual macro code. Other sections may be included as needed to explain with more detail the usage of the macro.
See [[GuiCommand model|GuiCommand model]] and macro pages like [[Macro Loft|Macro Loft]] and [[Macro Site From Contours|Macro Site From Contours]] to see how macros should be documented. At least two sections should be included, a {{Emphasis|Description}} section with general usage information, and a {{Emphasis|Script}} section to hold the actual macro code. Other sections may be included as needed to explain with more detail the usage of the macro.


<!--T:5-->
If a macro provides a well defined functionality, and is well documented, it could be included eventually as part of a new or an existing [[Workbenches|workbench]].
If a macro provides a well defined functionality, and is well documented, it could be included eventually as part of a new or an existing [[Workbenches|workbench]].


== New macro page ==
== New macro page == <!--T:6-->
Create a new page for the macro starting with the word {{incode|Macro_}}, for example, {{incode|Macro_Excellent_Modification}}. The link can be used without underscores as {{incode|<nowiki>[[Macro Excellent Modification]]</nowiki>}}, which results in [[Macro Excellent Modification]]; the spaces are automatically converted to underscores.


<!--T:7-->
Create a new page for the macro starting with the word {{incode|Macro_}}, for example, {{incode|Macro_Excellent_Modification}}. The link can be used without underscores as {{incode|<nowiki>[[Macro Excellent Modification|Macro Excellent Modification]]</nowiki>}}, which results in [[Macro Excellent Modification|Macro Excellent Modification]]; the spaces are automatically converted to underscores.

<!--T:8-->
In the new page you should use [[Template:Macro]] at the top, with a minimum of information:
In the new page you should use [[Template:Macro]] at the top, with a minimum of information:
</translate>
</translate>
Line 25: Line 32:
<translate>
<translate>


<!--T:9-->
You can add a custom icon if it doesn't have the same name as the macro; you can also add other fields of information.
You can add a custom icon if it doesn't have the same name as the macro; you can also add other fields of information.
</translate>
</translate>
Line 38: Line 46:
<translate>
<translate>


<!--T:10-->
When translating the page, use a localized template. You need to specify the name with the two letter language code ({{incode|/fr}}, {{incode|/it}}, {{incode|/de}}), and you need to indicate the icon explicitly.
When translating the page, use a localized template. You need to specify the name with the two letter language code ({{incode|/fr}}, {{incode|/it}}, {{incode|/de}}), and you need to indicate the icon explicitly
</translate>
</translate>
<nowiki>{{Macro/fr
<nowiki>{{Macro/fr
|Name=Macro Excellent Modification
|Name=Macro Excellent Modification translated
|Name/fr=Macro Excellent Modification
|Icon=Macro_Excellent_Modification.svg
|Icon=Macro_Excellent_Modification.svg
|Description=(Translated description)
|Description=(Translated description)
Line 50: Line 58:
<translate>
<translate>


<!--T:11-->
* Use [[:Special:Upload]] to upload the custom icon in [[SVG]] or PNG formats. It should have the same name as the macro.
or use the {{incode|Translate}} field
* Otherwise it will default to <code>Icon=Text-x-python.png</code> [[Image:Text-x-python.png|32px]].


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

<!--T:12-->
* Use [[:Special:Upload]] to upload the custom icon in [[SVG|SVG]] or PNG formats. It should have the same name as the macro.
* Otherwise it will default to <code>Icon=Text-x-python.svg</code> [[Image:Text-x-python.svg|32px]].
* For the macro used in the Python console by FreeCAD use <code>Icon=Text_console_python.png</code> [[Image:Text_console_python.png|32px]].
* For the example video macro use this skeleton of the icon [[Image:Text_Video_Movie.png|32px]] and fill the screen for obtain ex: [[Image:Macro_crank_simul.png|32px]] and save the new icon with the same name of your macro.

<!--T:13-->
[[Template:Macro]] will put the information on using and installing the macros in every page.
[[Template:Macro]] will put the information on using and installing the macros in every page.


Line 58: Line 83:
[[Image:Macro Recipes MacroHowToInstall.png|200px]]
[[Image:Macro Recipes MacroHowToInstall.png|200px]]
<translate>
<translate>
<!--T:14-->
{{Caption|[[How to install macros]] and [[Customize Toolbars|customize toolbars]] links in the infobox in each macro page}}
{{Caption|[[How to install macros]] and [[Customize Toolbars|customize toolbars]] links in the infobox in each macro page}}




=== Adding the macro documentation ===
=== Adding the macro documentation === <!--T:15-->


<!--T:16-->
* Just like a [[Gui Command]], explain what the macro does, its inputs, outputs, options, and limitations, if any.
* Just like a [[Gui Command|Gui Command]], explain what the macro does, its inputs, outputs, options, and limitations, if any.
* Add one or more images to clarify its usage.
* Include a personalized icon in [[SVG|SVG]] or PNG format for your macro so that other users can include it in a custom toolbar.
* If the macro performs a complex task, consider adding an animated GIF that shows its capabilities. The GIF image should have a maximum size of 500 x 500 pixels; if the GIF is bigger, the animation may not work. Do not resize the GIF as the wiki will not play resized GIFs.
* Mention related macros and workbenches that complement the function of this macro.
* Add one or more images to clarify the usage of your tool.
* If the macro performs a complex task, consider adding an animated GIF to showcase its capabilities. The GIF image should have a maximum size of 500 x 500 pixels; if the GIF is bigger, the animation may not work. Do not resize the GIF as the wiki will not play resized GIFs.
* Mention related macros and workbenches that complement the function of this tool.
* Mention the version of FreeCAD used to create the macro. This information can be gathered from {{MenuCommand|Help → About FreeCAD → Copy to clipboard}}.
* Mention the version of FreeCAD used to create the macro. This information can be gathered from {{MenuCommand|Help → About FreeCAD → Copy to clipboard}}.


<!--T:17-->
:When this information is pasted, it looks like this
:When this information is pasted, it looks like this
</translate>
</translate>
Line 87: Line 116:
<translate>
<translate>


<!--T:18-->
Consider adding this information in a comment block inside the code of the macro.
Consider adding this information in a comment block inside the code of the macro.


=== Adding the macro code ===
=== Adding the macro code === <!--T:19-->


<!--T:20-->
Inside the {{Emphasis|Script}} section, use [[Template:Code]] to place the code of the macro in the page. This will create a block of text that uses monospace font, which will preserve the whitespace that is essential for [[Python]].
Inside the {{Emphasis|Script}} section, use [[Template:MacroCode]] to place the code of the macro in the page. This will create a block of text that uses monospace font, which will preserve the whitespace that is essential for [[Python|Python]].
<nowiki>{{Code|code=

<!--T:40-->
If the block of code contains the characters <code>{{ }}</code> (double closing brace and opening brace) or <code>{{!}}</code> (vertical bar), the <code>&lt;nowiki&gt; ... &lt;/nowiki&gt;</code> tags can be added explicitly to allow displaying these special symbols.

<!--T:42-->
This [[Template:MacroCode]] essentially generates a block of HTML tags <code>&lt;pre&gt; ... &lt;/pre&gt;</code>, so these can be used directly instead of using the template. The [[Std_AddonMgr|Addon Manager]] will search for the biggest such block and use it for the body of the macro.

</translate>
<nowiki>{{MacroCode|code=


«Your code should be here»
«Your code should be here»


}}</nowiki>
}}
<translate>
</nowiki>

<!--T:43-->
Or if it includes the vertical bar <code>{{!}}</code>.
</translate>
<nowiki>{{MacroCode|code=
&lt;nowiki&gt;

«Your code should be here»

&lt;/nowiki&gt;
}}</nowiki>
<translate>

<!--T:44-->
Or
</translate>
<nowiki><pre>

«Your code should be here»

</pre></nowiki>
<translate>


<!--T:23-->
Add header information before your actual code.
Add header information before your actual code.
</translate>
</translate>
<nowiki>{{Code|code=
<nowiki>{{MacroCode|code=
__Title__="Title_Of_macro"
__Title__="Title_Of_macro"
__Author__ = "User_Name"
__Author__ = "User_Name"
Line 120: Line 182:
<translate>
<translate>


<!--T:24-->
This information can be used by the [https://github.com/FreeCAD/FreeCAD-addons addons_installer.FCMacro] macro, or by the [http://forum.freecadweb.org/viewtopic.php?t=10556 Plugin Loader] program, to install the macro and check for new versions. Starting with FreeCAD 0.17, this information is also used by the [[Addon Manager]], which downloads the macro from the [https://github.com/FreeCAD/FreeCAD-macros FreeCAD-macros] repository.
Starting with FreeCAD 0.17, this information is used by the [[Std_AddonMgr|Addon Manager]], which downloads the macro from the [https://github.com/FreeCAD/FreeCAD-macros FreeCAD-macros] repository.


=== Adding macro code outside of the wiki ===
=== Adding macro code outside of the wiki === <!--T:25-->


<!--T:26-->
If your macro is too big that it exceeds 64 KB, it won't be able to be hosted on the wiki. In this case, use [[Template:Codeextralink]] with a link to the raw web address of the code.
If your macro is too big that it exceeds 64 KB, it won't be able to be hosted on the wiki. In this case, use [[Template:Codeextralink]] with a link to the raw web address of the code.


<!--T:27-->
For example:
For example:
</translate>
</translate>
Line 131: Line 196:
<translate>
<translate>


<!--T:28-->
It will be displayed as:
It will be displayed as:
</translate>
</translate>
Line 136: Line 202:
<translate>
<translate>


<!--T:29-->
This template must be placed at the beginning of the macro page, in the {{Emphasis|Description}} section. It must be the first block of code in the page so that the [[Addon Manager]] can automatically detect it and import it. See [[Macro CirclePlus]] for an example of the usage.
This template must be placed at the beginning of the macro page, in the {{Emphasis|Description}} section. It must be the first block of code in the page so that the [[Std_AddonMgr|Addon Manager]] [[File:Std_AddonMgr.svg|24px]] can automatically detect it and import it. See [[Macro CirclePlus|Macro CirclePlus]] for an example of the usage.

<!--T:39-->
{{ColoredParagraph|'''PS:''' In case upgrade in GitHub the path of the RAW code is modified not forgotten modify the link in the Codeextralink template.}}


== Adding the new macro to the wiki repository ==
== Adding the new macro to the wiki repository == <!--T:30-->


<!--T:31-->
Use [[Template:MacroLink]] to include a line in the appropriate category in [[Macros recipes]]; create a new category if needed.
Use [[Template:MacroLink]] to include a line in the appropriate category in [[Macros recipes|Macros recipes]]; create a new category if needed.


</translate>
</translate>
Line 150: Line 221:
<translate>
<translate>


<!--T:32-->
* The first argument is the name of the macro page in the wiki.
* The first argument is the name of the macro page in the wiki.
* The second argument is the displayed text, which may be different from the page name.
* The second argument is the displayed text, which may be different from the page name. This will create a link to the first argument, showing the second argument as the text.
* This will create a link to the first argument, showing the second argument as the text.
* A short description of the macro comes after the colon.
* A short description of the macro comes after the colon.


<!--T:33-->
You can also use the optional parameter <code>Icon=</code> to specify the image file that will be placed at the start of the line. The icon should be an [[SVG]] or a PNG file, and should have the same name as your macro. If this parameter is not given it will use the default icon for a [[Python]] script [[Image:Text-x-python.png|24px]].
You can also use the optional parameter <code>Icon=</code> to specify the image file that will be placed at the start of the line. The icon should be an [[SVG|SVG]] or a PNG file, and should have the same name as your macro. If this parameter is not given it will use the default icon for a [[Python|Python]] script [[Image:Text-x-python.svg|24px]].
</translate>
</translate>
{{Code|code=
{{Code|code=
Line 164: Line 236:
<translate>
<translate>


<!--T:34-->
To localize this template, use the appropriate language link in the first argument.
To localize this template, use the appropriate language link in the first argument.
</translate>
</translate>
{{Code|code=
{{Code|code=
<nowiki>
<nowiki>
* {{MacroLink|Macro_Excellent_Modification/fr|Macro Excellent Modification}}: the macro described in a short sentence.
* {{MacroLink|Macro_Excellent_Modification/fr|Macro Excellent Modification}}: (translated description)
</nowiki>
</nowiki>
}}
}}
<translate>
<translate>


== Adding the new macro to the central repository ==
== Adding the new macro to the central repository == <!--T:35-->


<!--T:36-->
To make a macro installable from the [[Addon Manager]] it should be included in the central [https://github.com/FreeCAD/FreeCAD-macros FreeCAD-macros] repository.
To make a macro installable from the [[Std_AddonMgr|Addon Manager]] it should be included in the central [https://github.com/FreeCAD/FreeCAD-macros FreeCAD-macros] repository.


<!--T:37-->
In order to include the macro there, first it must be reviewed by the FreeCAD community in the [https://forum.freecadweb.org/viewforum.php?f=22 Python scripting and macros] subforum. Once this is done, the FreeCAD-macros repository should be forked, the new macro should be included in a branch, and then the branch should be pushed and merged into the upstream repository.
In order to include the macro there, first it must be reviewed by the FreeCAD community in the [https://forum.freecadweb.org/viewforum.php?f=22 Python scripting and macros] subforum. Once this is done, the FreeCAD-macros repository should be forked, the new macro should be included in a branch, and then the branch should be pushed and merged into the upstream repository.


[[Category:Macros]]
[[Category:User Documentation]]
</translate>
</translate>
[[Category:Macros{{#translation:}}]]
[[Category:User Documentation{{#translation:}}]]

Revision as of 19:27, 3 November 2021

Description

All macros should be properly documented in the same way Gui Commands are documented. They should have an individual wiki page, and should be listed in one of the categories in Macros recipes.

The Macros recipes page has a good selection of macros created by experienced users, and many of them can be directly installed from the Addon Manager.

See GuiCommand model and macro pages like Macro Loft and Macro Site From Contours to see how macros should be documented. At least two sections should be included, a Description section with general usage information, and a Script section to hold the actual macro code. Other sections may be included as needed to explain with more detail the usage of the macro.

If a macro provides a well defined functionality, and is well documented, it could be included eventually as part of a new or an existing workbench.

New macro page

Create a new page for the macro starting with the word Macro_, for example, Macro_Excellent_Modification. The link can be used without underscores as [[Macro Excellent Modification|Macro Excellent Modification]], which results in Macro Excellent Modification; the spaces are automatically converted to underscores.

In the new page you should use Template:Macro at the top, with a minimum of information:

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

You can add a custom icon if it doesn't have the same name as the macro; you can also add other fields of 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]]
}}

When translating the page, use a localized template. You need to specify the name with the two letter language code (/fr, /it, /de), and you need to indicate the icon explicitly

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

or use the Translate field

{{Macro/fr
|Name=Macro Excellent Modification
|Translate=Macro Excellent Modification translated
|Description=(Translated description)
|Author=your username
|Date=2018-11-30
}}
  • Use Special:Upload to upload the custom icon in SVG or PNG formats. It should have the same name as the macro.
  • Otherwise it will default to Icon=Text-x-python.svg .
  • For the macro used in the Python console by FreeCAD use Icon=Text_console_python.png .
  • For the example video macro use this skeleton of the icon and fill the screen for obtain ex: and save the new icon with the same name of your macro.

Template:Macro will put the information on using and installing the macros in every page.

How to install macros and customize toolbars links in the infobox in each macro page


Adding the macro documentation

  • Just like a Gui Command, explain what the macro does, its inputs, outputs, options, and limitations, if any.
  • Include a personalized icon in SVG or PNG format for your macro so that other users can include it in a custom toolbar.
  • Add one or more images to clarify the usage of your tool.
  • If the macro performs a complex task, consider adding an animated GIF to showcase its capabilities. The GIF image should have a maximum size of 500 x 500 pixels; if the GIF is bigger, the animation may not work. Do not resize the GIF as the wiki will not play resized GIFs.
  • Mention related macros and workbenches that complement the function of this tool.
  • Mention the version of FreeCAD used to create the macro. This information can be gathered from Help → About FreeCAD → Copy to clipboard.
When this information is pasted, it looks like this
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)

Consider adding this information in a comment block inside the code of the macro.

Adding the macro code

Inside the Script section, use Template:MacroCode to place the code of the macro in the page. This will create a block of text that uses monospace font, which will preserve the whitespace that is essential for Python.

If the block of code contains the characters {{ }} (double closing brace and opening brace) or | (vertical bar), the <nowiki> ... </nowiki> tags can be added explicitly to allow displaying these special symbols.

This Template:MacroCode essentially generates a block of HTML tags <pre> ... </pre>, so these can be used directly instead of using the template. The Addon Manager will search for the biggest such block and use it for the body of the macro.

{{MacroCode|code=

«Your code should be here»

}}

Or if it includes the vertical bar |.

{{MacroCode|code=
<nowiki>

«Your code should be here»

</nowiki>
}}

Or

<pre>

«Your code should be here»

</pre>

Add header information before your actual code.

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

Starting with FreeCAD 0.17, this information is used by the Addon Manager, which downloads the macro from the FreeCAD-macros repository.

Adding macro code outside of the wiki

If your macro is too big that it exceeds 64 KB, it won't be able to be hosted on the wiki. In this case, use Template:Codeextralink with a link to the raw web address of the code.

For example:

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

It will be displayed as:

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


This template must be placed at the beginning of the macro page, in the Description section. It must be the first block of code in the page so that the Addon Manager can automatically detect it and import it. See Macro CirclePlus for an example of the usage.

PS: In case upgrade in GitHub the path of the RAW code is modified not forgotten modify the link in the Codeextralink template.

Adding the new macro to the wiki repository

Use Template:MacroLink to include a line in the appropriate category in Macros recipes; create a new category if needed.

* {{MacroLink|Macro_Excellent_Modification|Macro Excellent Modification}}: the macro described in a short sentence.
  • The first argument is the name of the macro page in the wiki.
  • The second argument is the displayed text, which may be different from the page name. This will create a link to the first argument, showing the second argument as the text.
  • A short description of the macro comes after the colon.

You can also use the optional parameter Icon= to specify the image file that will be placed at the start of the line. The icon should be an SVG or a PNG file, and should have the same name as your macro. If this parameter is not given it will use the default icon for a Python script .

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

To localize this template, use the appropriate language link in the first argument.

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

Adding the new macro to the central repository

To make a macro installable from the Addon Manager it should be included in the central FreeCAD-macros repository.

In order to include the macro there, first it must be reviewed by the FreeCAD community in the Python scripting and macros subforum. Once this is done, the FreeCAD-macros repository should be forked, the new macro should be included in a branch, and then the branch should be pushed and merged into the upstream repository.