README: Create a section on how to create a Workbench

[luzpaz]

Relevant links:

• https://github.com/FreeCAD/Workbench-Starterkit
• https://freecadweb.org/wiki/Workbench_creation

[luzpaz]

CC @looooo

[looooo]

@luzpaz the starter-workbench is not really related to FreeCAD-addons. I guess it should be possible to also integrate pip-installable modules in the addon-manager but I did not had the time to think about this. Something to think about in the next year.

[luzpaz]

It's not related ?
Isn't it a template for a workbench ?
Addons are workbenches, modules, and macros... seems related to me.

[looooo]

yes it's a template for a work-bench / module. But I don't want to mix this with the old way of creating workbenches, as this will lead to misunderstandings. Currently both ways are supported, but I guess we should think about how to make both ways more compatible as the old-style workbenches won't go away. Also most users that trying to code something for freecad have not enough python background to understand why new way of creating workbenches is better.
But yes, I will try to work on documentation if time allows.

[pierrard]

Many thanks Lorenz (Loooo) and other contributors for all you do for the community !!
I am slowly building a DIY router, 5 axis milling, and will very much appreciate the use of FreeCAD for the CAD and CAM once my hardware is ready (slow down by the cost of the parts now).
MANY THANKS!

[luzpaz]

@looooo I see, thanks for explaining that. I didn't understand there was a 'better' preference. IMHO, we could create documentation for this pre-0.18 so any of the users that 'come in to the fold' of FreeCAD can make a more educated decision.

[looooo]

@pierrard I am only doing what I need / like to work at. There are others like @luzpaz who try to move FreeCAD in the right direction. Best to thank the whole community, which include a lot of smart people fighting for a great project ; ).

@luzpaz yes you are right. I always underestimate the impact of docs : ).

[luzpaz]

@joelgraff perhaps you could weigh in on workbench creation as well at some point ? (i know your todo list is yuuuuge but nonetheless, please consider thanks!!!)

[joelgraff]

@luzpaz - Thanks for mentioning this. Currently, I've forked the starter kit and am, a little bit at a time, trying to build out a general layout that is maintainable and scalable for small to mid-sized Python workbenches. Specifically, I feel a workbench's functions are best divided across individual "Tasks" and code needs to be organized to reflect that.

For example:

• init_gui.py should never have anything more than the command class imports and toolbar / context menu / menu layout code.
• A command class should only setup a task and clean up after it
• A base task class should do two things: initialize the task panel ui, and kick off the task-specific subclasses, where all of the custom code really belongs.

Of course, there are exceptions (like a command that simply executes an external program, or just opens a file), but for more complex tasks, I really think that sort of structure should be encouraged / enforced where possible.

Without a clear structure in place to mange the various workbench command / task use cases, we cannot write clear, useful developer documentation. I realize it's no good trying to enforce absolute standards, but the goal is to provide a clean and well organized picture of how everything fits together rather than leave new devs to their own devices to hack together something that works, but may become unmaintainable as the workbench scope scales.

[luzpaz]

@joelgraff
I resonate with everything you wrote and I'm very glad this discussion is progressing. Especially:

Without a clear structure in place to mange the various workbench command / task use cases, we cannot write clear, useful developer documentation. I realize it's no good trying to enforce absolute standards, but the goal is to provide a clean and well organized picture of how everything fits together rather than leave new devs to their own devices to hack together something that works, but may become unmaintainable as the workbench scope scales.

I think I'll pin this issue so it's of priority.

[luzpaz]

yikes, got to get around to doing this.

[joelgraff]

I had a framework of my own cobbled together, but I think I lost track of it, too. *Joel Graff, P.E.* *LinkedIn:* https://www.linkedin.com/in/joelcgraff

…

On Wed, Mar 10, 2021 at 5:41 AM luzpaz ***@***.***> wrote: yikes, got to get around to doing this. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#104 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA2VMSXEFLKNSY7VVBJRUDLTC5EHJANCNFSM4FYCBWNA> .

[lukh]

Hello there,
I wrote my first workbench for FreeCAD (pure python) and found it quite hard to get access to "good doc" (ie, up to date, following standard python rules, etc)
The default template give informations, but not how to create a task for instance,
The wiki is... (sorry :s ) complicated to get to, too many pages, in different sections, (maybe the scripting page are okay, but I couldn't find infos like; where to put the code snippet, I had to figure it out with some existing WB, (but not specifically up-to-date... or Draft Workbench, that uses a lot of shared / polymorphism code, so hard to follow when you want understand how a WB works...

I want to help, I can help @joelgraff on the template, or on the wiki; I would probably need validation that the code I wrote is good enough for that

(BTW: learning FreeCAD for one year or so, love it, works like a charm :) ),

Bests