Detecting when a wiki page for a FC command doesn't have a (or has an incomplete) 'Scripting' section

Discussions about the wiki documentation of FreeCAD and its translation.
User avatar
Kunda1
Posts: 7337
Joined: Thu Jan 05, 2017 9:03 pm

Detecting when a wiki page for a FC command doesn't have a (or has an incomplete) 'Scripting' section

Postby Kunda1 » Thu Jan 09, 2020 4:56 pm

Thinking of using the WikiRobots bot to test if a FC command documentation page does or doesn't have a Scripting section.

I'm thinking initially of just simply checking the URL https://freecadweb.org/wiki/<CMD_Name>#Scripting and then creating the logic to understand if that section exists and what does it contain.
Want to contribute back to FC? Checkout:
#lowhangingfruit | Use the Source, Luke. | How to Help FreeCAD | How to report FC bugs and features
vocx
Posts: 4001
Joined: Thu Oct 18, 2018 9:18 pm

Re: Detecting when a wiki page for a FC command doesn't have a (or has an incomplete) 'Scripting' section

Postby vocx » Thu Jan 09, 2020 7:25 pm

Kunda1 wrote:
Thu Jan 09, 2020 4:56 pm
Thinking of using the WikiRobots bot to test if a FC command documentation page does or doesn't have a Scripting section.
...
This is fine.

Just a word of caution for editors. I originally started adding "Scripting" sections to GUI commands following the example of the Draft Workbench, which had those sections already. The way this workbench is written, it makes total sense, but this may not be the case for other workbenches.

The idea is to provide a basic script that teaches users to work with a particular tool quickly. It is not meant to be extensive or the full programming documentation (API).

Further documentation should be generated automatically by Doxygen, by parsing the documentation strings in the case of purely Python-based commands. For C++ commands, often a there is no easy way to generate user documentation, so a basic scripting section is necessary.

Moreover, we should distinguish between a GUI-less function and a GUI command (button). Almost every GUI command in Draft has a corresponding GUI-less function. So the GUI-less function is what is described in the Scripting section. For other workbenches this may not be the case because they only have GUI commands (buttons) but no GUI-less functions.

Said in another way, just because a GUI tool lacks a "Scripting" section, that doesn't mean the documentation is incomplete. Almost everything can be done in the Python console but maybe some tools are inherently graphical and don't require a "Scripting" section.
Always add the important information to your posts if you need help.
To support the documentation effort, and code development, your donation is appreciated: paypal.
User avatar
Kunda1
Posts: 7337
Joined: Thu Jan 05, 2017 9:03 pm

Re: Detecting when a wiki page for a FC command doesn't have a (or has an incomplete) 'Scripting' section

Postby Kunda1 » Thu Jan 09, 2020 11:44 pm

vocx wrote:
Thu Jan 09, 2020 7:25 pm
Said in another way, just because a GUI tool lacks a "Scripting" section, that doesn't mean the documentation is incomplete. Almost everything can be done in the Python console but maybe some tools are inherently graphical and don't require a "Scripting" section.
Thanks for the feedback on this. You bring up some very valid points to consider. From a uniformity standard, should we have a subsection within the scripting section for GUI scripts and non GUI based scripts. And therefore in the context of a command that doesn't have a GUI based scripting example or vice-versa to mention it in said subsection?

AKA:
Scripting
  • GUI
  • Non-GUI
Want to contribute back to FC? Checkout:
#lowhangingfruit | Use the Source, Luke. | How to Help FreeCAD | How to report FC bugs and features
vocx
Posts: 4001
Joined: Thu Oct 18, 2018 9:18 pm

Re: Detecting when a wiki page for a FC command doesn't have a (or has an incomplete) 'Scripting' section

Postby vocx » Fri Jan 10, 2020 1:34 am

Kunda1 wrote:
Thu Jan 09, 2020 11:44 pm
... From a uniformity standard, should we have a subsection within the scripting section for GUI scripts and non GUI based scripts. ...
I don't think this is necessary. It's just natural when a tool requires a scripting section and when it doesn't.

What I mean is this. The Draft Rectangle tool is a GUI command (button). Underneath it, it calls the GUI-less Draft.makeRectangle function. Therefore, the "Scripting" section documents this function.

Some commands are just GUI commands, and don't have a proper scripting (GUI-less) interface, like, say, Std_About. This command can be run from the terminal as

Code: Select all

Gui.runCommand('Std_About',0)
But that's not suitable for GUI-less scripting, because it just runs the same GUI command as when you choose this command from the menu (Help -> About FreeCAD).
Always add the important information to your posts if you need help.
To support the documentation effort, and code development, your donation is appreciated: paypal.