New Feature - Addon Manager for developers

[galou_breizh]

I think that there are indeed a need for the presence of some "utility" functions in a central place for macro developers (e.g. shortcuts to the logging functions or console logging plus GUI information in one function, or detecting the type of object). The question is whether this needs to be in a separate workbench rather than being standard FreeCAD, As long as we don't have any solution to manage dependencies, I think it's better to have such functions in an official FreeCAD workbench (I mean in the main repository). I don't see the need for any menu right now.

Gaël

[Joel_graff]

So, I'm trying my hand at reworking the workbench starter kit to make it a little more friendly to developers.

You can see my fork here:

https://github.com/joelgraff/Workbench-Starterkit

Thus far I've done the following:

1. Made some relatively minor modifications to the directory structure for better code organization
2. Incorporated my approach to managing init_gui.py with the current file (I retained most of the original file and adapted my code accordingly)
3. Added "tutorial" documentation to init_gui.py. It's decorated in comment lines made up of tilde symbols (#~~~~~~~~).

The tutorial documentation is designed to allow a new dev to explore the workbench code for themselves and get a quick explanation of why things are as they are. I'm trying to write it in a clear, easy-to-read format that doesn't get too heavily into the details.

I prefer this approach because it puts wiki-level documentation right where the developer is most likely to go. Unfortunately, that means they have to explicitly delete it after the fact. If this is a valuable approach to documenting workbench development, maybe a solution can be found so it doesn't have to be there for users who don't want it.

I plan on modifying the rest of the starter kit codebase in similar fashion... Perhaps providing "breadcrumbs" in each file, suggesting to a new dev which file they should check out next as they familiarize themselves with the Python workbench structure.

[triplus]

As you are investing some effort, i took a quick look and here are some thoughts. Everything looks rather technical, involves some more in-depth knowledge, there are a lot of loose ends involved. In short the whole thing is a bit overwhelming. I feel that better to go in such direction:

https://docs.djangoproject.com/en/2.2/intro/tutorial01/

Therefore somebody having a minimal knowledge of Python should be able to create a FreeCAD module (workbench) and a command in it. In lets say 30 minutes. After best to gather some more feedback first, and to decide after, if post-intro tutorial is needed, and what it should be about. For example "Accessing 3D Viewport through Python", practical examples. Here there could in addition be some module available, by default, providing examples in code.

P.S. Or to use an approach, where you would have an entry, "How to create a FreeCAD command". Such entry would be rather short and easy to grasp. It would have a note above, "To create a FreeCAD command, you need to create a FreeCAD module first.". Such note would link to another such short and easy to grasp piece of documentation. In addition to TOC, this would therefore help new developers, to have a better overview and some guidance at all times.

[Joel_graff]

As you are investing some effort, i took a quick look and here are some thoughts. Everything looks rather technical, involves some more in-depth knowledge, there are a lot of loose ends involved. In short the whole thing is a bit overwhelming. I feel that better to go in such direction:

That's certainly fine by me. I didn't intend in-line comments to replace wiki documentation - certainly not for complete beginners. Rather I wanted to point out the things in each file that a dev is likely to touch, what it is, and how they want to deal with that. Someone who does know a good bit about Python and is only limited by understanding how a FreeCAD workbench is structured will probably prefer to jump in before reading wiki tutorials. Those people would likely find those in-line, more technical comments helpful. I say that because I'm one of those. So I guess I'm really writing it for me. I hate reading wiki's.

Nevertheless, I'm not really sold on doing it this way, and I won't bother if it doesn't seem like a valuable additional level of documentation.

Regardless, I'll continue to rework the starter kit and post updates here. The ultimate goal is to have a clean framework that covers most use cases and provides a ready, simple way to organize code for small to medium-sized workbenches. Personally, I think good code organization is one of the hardest parts of development and would be really valuable to provide a dev a structure that makes it obvious where to stick new code as they develop it.

[vocx]

Someone who does know a good bit about Python and is only limited by understanding how a FreeCAD workbench is structured will probably prefer to jump in before reading wiki tutorials.

I think this is a fair assessment.

I think what we need is a combination of both approaches. A wiki step by step how to create a command, and build a workbench, and your approach of having that workbench already made, needing only specific changes to that workbench.

In particular, I would also like to fix the terminology, obviously "Module" is any piece of code that could be loaded that isn't part of the core. However, in FreeCAD, "Module" and "Workbench" are used almost interchangeably. I'd like to reserve the term "Module" for those pieces of code that are supporting FreeCAD, and are basically invisible to the user, while "Workbench" is more like a graphical toolbox. So in my mind, things like Tux, Show, or Addon Manager, things that provide supporting functions to FreeCAD are "modules", while things like Part, TechDraw, FEM, are "workbenches" because they provide actual tools for the user to draw shapes and objects. From a programming point of view there is no difference, but I think making this distinction is good to avoid confusing the users.

[triplus]

Reference:

https://forum.freecadweb.org/viewtopic.php?f=9&t=37584

[Joel_graff]

Ok, so I've taken a little time to flesh out what the key elements that I feel are missing to the Workbench Starter Kit.

https://github.com/joelgraff/Workbench-Starterkit

I won't say this is complete, or that my implementation is ideal. But I feel it provides enough structure to get a workbench started, and is flexible enough to accommodate quite a bit of growth. In my view, the three key files to a workbench task are initgui.py, the command class, and the task class.

Of course, not every task requires this structure. At a bare minimum, however, each task should exist in a separate command class. Such tasks that would be appropriate for the command class only might be basic file actions or one-off macros that do some otherwise menial task which is more or less 'atomic' in scope. That is, it doesn't have a lot of moving parts or complexity.

As tasks grow more complex, a separate task class should be used. Again, it may be enough to contain the entire task in a single file, but the task class itself should really only be responsible for setting up the global state for the task to be performed, leaving the details to task-specific modules.

I've also created a 'BaseTask' class which provides a lot of the default / global state that any given task will likely need. This moves a lot of boilerplate code out of the main task class, keeping things cleaner for the developer.

Apart from that, there's a number of issues I've ignored in an effort not to overcomplicate things, though I defer to anyone with a strong opinion on that.

Finally, I would be happy to take a stab at documenting this, though I find doing it on a Github Wiki to be preferable to using FreeCAD's mediawiki. I don't want to fragment our documentation across multiple sources, so no doubt something ought to be done in the freeCAD wiki, but because this is a topic driven almost entirely by documenting a bunch of source code, doing a Github wiki makes sense to me.

[Kunda1]

Finally, I would be happy to take a stab at documenting this, though I find doing it on a Github Wiki to be preferable to using FreeCAD's mediawiki. I don't want to fragment our documentation across multiple sources, so no doubt something ought to be done in the freeCAD wiki, but because this is a topic driven almost entirely by documenting a bunch of source code, doing a Github wiki makes sense to me.

The mediawiki documentation process is very frustrating to me, so I support you documentation efforts on github and then simply pointing to github from mediawiki. Of course, I'm also not interested in fragmenting documentation. For practical purposes I think it's appropriate here.

[Joel_graff]

The mediawiki documentation process is very frustrating to me, so I support you documentation efforts on github and then simply pointing to github from mediawiki. Of course, I'm also not interested in fragmenting documentation. For practical purposes I think it's appropriate here.

Ok, good.

I don't know who maintains the repo in the FreeCAD main account. Is that @looo? @triplus? In any case, I would like to get some consensus / make changes / merge a PR before I start writing wiki docs for it...

[vocx]

... In my view, the three key files to a workbench task are initgui.py, the command class, and the task class.
...

I'm a bit confused by what you call a "task". Can you explain a bit? Is it the same as a "Gui Command"? Basically a button or menu that produces a result? Is it something that you run with

Code: Select all

Gui.runCommand("Task")

Of course, not every task requires this structure. At a bare minimum, however, each task should exist in a separate command class. Such tasks that would be appropriate for the command class only might be basic file actions or one-off macros that do some otherwise menial task which is more or less 'atomic' in scope. That is, it doesn't have a lot of moving parts or complexity.

Maybe you can comment a bit on this long post, [Discussion] Splitting Draft tools into their own modules.

I'm looking into re-organizing the Draft Workbench code, so I've come up with some ideas.

Basically, I like this structure

Code: Select all

Draft/
  Draft.py
  draftobjects/
  draftguitools/
  drafttaskpanels/
  draftviewproviders/
  Resources/
    icons/
    ui/

Draft.py is the module that provides programming interfaces that other developers and users can use to write their own macros. Draftobjects/ has code that creates scritped objects; they don't require the GUI at all. Draftguitools/ provides code for the "graphical commands", or "Gui Commands", buttons and menus. Very often these commands will require a task panel. So, the task panel .ui files (QtCreator) will be stored in Resources/ui, but the code to connect that interface with the GuiCommand will be in drafttaskpanels/. The draftviewproviders/ module will provide the code for the view providers for the scripted objects defined in draftobjects/; this is done to have separation of GUI and non-GUI code, just like some C++ workbenches do, see Part for example in the source code.

Of course, I would also provide some additional modules for supporting utilities. For example, in Draft, a lot of small functions are defined to do things like get the object type, truncate the name, get the view direction, test for clones of objects, etc. All these auxiliary tools can be placed in separate submodules, like draftutilities/, draftguiutilities/, or more.