Scripted Object documentation

Have some feature requests, feedback, cool stuff to share, or want to know where FreeCAD is going? This is the place.
Forum rules
Be nice to others! Read the FreeCAD code of conduct!
User avatar
Joel_graff
Veteran
Posts: 1949
Joined: Fri Apr 28, 2017 4:23 pm
Contact:

Re: Scripted Object documentation

Post by Joel_graff »

I think I have the first portion of documentation about where I want it.

It's a complete example of how to build a basic FeaturePython object that implements custom properties and the very basics of event trapping. I plan on continuing, demonstrating how to build a 3D object using the execute() function, trapping other document events, and demonstrating the value of Part::FeaturePython over App::FeaturePython. The last part should focus on ViewProviders.

Other than the tutorial, I want to greatly expand the documentation on App::Property types with code examples, demonstrate implementations of all of the available FeaturePython types (like App;:DocumentObjectPython, Sketcher::SketchObjectPython, etc.), and include maybe some common / useful FeaturePython recipes (perhaps in the code recipes portion of the wiki).

It'll probably take a while, though. :)
FreeCAD Trails workbench for transportation engineering: https://www.github.com/joelgraff/freecad.trails

pivy_trackers 2D coin3D library: https://www.github.com/joelgraff/pivy_trackers
keithsloan52
Veteran
Posts: 2756
Joined: Mon Feb 27, 2012 5:31 pm

Re: Scripted Object documentation

Post by keithsloan52 »

Gets my vote.

Would like to see better documentation on the less obvious App::Properties ( Well less obvious to me at least )

App::PropertyEnumeration
App::PropertyIntegerSet
App::PropertyMap
App::PropertyLink
App::PropertyLinkSub
App::PropertyLinkList
App::PropertyLinkSubList
App::PropertyFileIncluded
Part::PropertyGeometryList
Part::PropertyShapeHistory

My efforts with FeaturePython Objects can be found at https://github.com/KeithSloan/FreeCAD_Python_GDML
But I think I had to query all things via the Forum and you answered/contributed to them all.
User avatar
Joel_graff
Veteran
Posts: 1949
Joined: Fri Apr 28, 2017 4:23 pm
Contact:

Re: Scripted Object documentation

Post by Joel_graff »

keithsloan52 wrote: Thu Mar 28, 2019 6:33 am Would like to see better documentation on the less obvious App::Properties ( Well less obvious to me at least )
I agree. I've used maybe two or three of those and it took a while to sort it out. Werner had to teach me how to use one of them for a complete lack of documentation, and he's really too busy managing C++ code to be bothered by Python questions. :)

keithsloan52 wrote: Thu Mar 28, 2019 6:33 am But I think I had to query all things via the Forum and you answered/contributed to them all.
It's fun - plus I get to learn a few things I didn't know!
FreeCAD Trails workbench for transportation engineering: https://www.github.com/joelgraff/freecad.trails

pivy_trackers 2D coin3D library: https://www.github.com/joelgraff/pivy_trackers
User avatar
Joel_graff
Veteran
Posts: 1949
Joined: Fri Apr 28, 2017 4:23 pm
Contact:

Re: Scripted Object documentation

Post by Joel_graff »

https://www.freecadweb.org/wiki/Creatin ... x,_Part_II

Added a second page to the FeaturePython documentation. Note, it's still a draft - very rough and I have one more section I want to add.

So as I'm working on this, a map is starting to present itself to me.

Additional documentation needs to include:

1. Separate pages for each FeaturePython object type with more explicit details, but building on this beginning tutorial (including Extensions, per @DeepSOIC)
2. A page with a table of the properties, what they are, and snippets describing how they work (as previously discussed)
3. More formal documentation on ViewProviders
4. Common or useful featurepython recipes
5. Troubleshooting tips and tricks (FAQ)

Comments welcome, as always. :)
FreeCAD Trails workbench for transportation engineering: https://www.github.com/joelgraff/freecad.trails

pivy_trackers 2D coin3D library: https://www.github.com/joelgraff/pivy_trackers
User avatar
Joel_graff
Veteran
Posts: 1949
Joined: Fri Apr 28, 2017 4:23 pm
Contact:

Re: Scripted Object documentation

Post by Joel_graff »

The second page of the FeaturePython tutorial is mostly complete.

Needs formatting work and translate tags, I guess, but otherwise, I think it's good enough. Also linked the two pages together.

The next piece to do might be the App::Properties.

For this, I think I want to detail each property type and give code examples of how to use it, along with screenshots, where applicable.

I'd also include basic techniques on how to implement / use properties.

That said, I'd love to hear best practices or get links to good examples. I have a few in mind already.

Also, I never really got a clear understanding of how property values get assigned myself - there's some cases where you can't just assign a value to a property directly, though those cases elude me at the moment. I actually defaulted to using setattr(obj, 'prop_name') because it was confusing me at one point...
FreeCAD Trails workbench for transportation engineering: https://www.github.com/joelgraff/freecad.trails

pivy_trackers 2D coin3D library: https://www.github.com/joelgraff/pivy_trackers
User avatar
Joel_graff
Veteran
Posts: 1949
Joined: Fri Apr 28, 2017 4:23 pm
Contact:

Re: Scripted Object documentation

Post by Joel_graff »

So @Renatorivo took it upon himself to update my FeaturePython custom properties page, as I simply created a stub and left it blank. I suppose I've neglected this effort in the last few weeks...

https://www.freecadweb.org/wiki/Feature ... Properties

That said, I wanted to develop some comprehensive documentation specific to each property type, though some of the properties I've never used or know little about. One of the questions that I never fully resolved was how to set properties.

That is, the property values can be assigned directly to the property itself or using the "Value" attribute, IIRC. I never really sorted that out and ultimately ended up doing something like:

Code: Select all

setattr(obj, prop_name)
to set property values. I take it the 'Value' attribute are for properties which take actual values (strings / floats) rather than references?
FreeCAD Trails workbench for transportation engineering: https://www.github.com/joelgraff/freecad.trails

pivy_trackers 2D coin3D library: https://www.github.com/joelgraff/pivy_trackers
vocx
Veteran
Posts: 5197
Joined: Thu Oct 18, 2018 9:18 pm

Re: Scripted Object documentation

Post by vocx »

Just general advice for wiki editing, Joel. Don't use two empty lines to separate paragraphs. It makes the text look very sparse and ugly.

Also, completely remove the manual breaks <br>. In the FreeCAD wiki I have seen pages with those manual breaks, but those pages were usually very old, with outdated information, written many years ago by who knows whom. Manual breaks are raw HTML elements, maybe they were required in a previous wiki (sourceforge?) but are completely unnecessary in a modern wiki. Leave a single empty line if you wish to start a new paragraph.
Always add the important information to your posts if you need help. Also see Tutorials and Video tutorials.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
User avatar
Joel_graff
Veteran
Posts: 1949
Joined: Fri Apr 28, 2017 4:23 pm
Contact:

Re: Scripted Object documentation

Post by Joel_graff »

vocx wrote: Tue May 28, 2019 6:50 pm Also, completely remove the manual breaks <br>. In the FreeCAD wiki I have seen pages with those manual breaks, but those pages were usually very old, with outdated information, written many years ago by who knows whom. Manual breaks are raw HTML elements, maybe they were required in a previous wiki (sourceforge?) but are completely unnecessary in a modern wiki. Leave a single empty line if you wish to start a new paragraph.
I took a look at the page again and I see what you mean - it's certainly more broken up than I intended. I'm used to writing blogs, where line breaks and visual space is used to help separate ideas and make the text more readable. Unfortunately, that doesn't seem to translate well to wiki's. Indeed, I found managing the formatting more difficult on a wiki than a blog post... Perhaps I just need to use more tables. :)

On the topic of <br> tags - I seem to remember learning long ago that in HTML, blank lines can be more ambiguous in how they're rendered than <br> tags, and I discovered that was the case with the wiki as well. That said, I really don't like using them.

When I have some time in the next few days, I'll go back and see if I can clean it up a bit. I need to figure out how to do this better, anyway.
FreeCAD Trails workbench for transportation engineering: https://www.github.com/joelgraff/freecad.trails

pivy_trackers 2D coin3D library: https://www.github.com/joelgraff/pivy_trackers
vocx
Veteran
Posts: 5197
Joined: Thu Oct 18, 2018 9:18 pm

Re: Scripted Object documentation

Post by vocx »

Joel_graff wrote: Tue May 28, 2019 8:07 pm I took a look at the page again and I see what you mean - it's certainly more broken up than I intended. I'm used to writing blogs, where line breaks and visual space is used to help separate ideas and make the text more readable.
I don't really understand when people say that wiki syntax is hard or even "esoteric". It's not. It's pretty simple. There is only a small amount of wiki markup that the user needs to know to produce a document. It's not so different from markdown, which everybody seems to think is so great nowadays.
Indeed, I found managing the formatting more difficult on a wiki than a blog post... Perhaps I just need to use more tables. :)
Formatting, just like anything in on the internet nowadays is controlled through style sheets. It should be no problem to adjust globally the fonts, or linespacing, and things like that by modifying the main wiki style sheets. But that is something normal users cannot do; that's the task of whoever the administrator of the wiki server is (Yorik, Werner, Kremitzki?). Don't worry about appearance too much. Worry about quality content. That should be the main task of the person working on documentation. You can always make it "pretty" later on.

Have you seen the book by Qingfeng? He documented a bunch of stuff in Github so that it's useful to future developers. Moreover, he placed it in Github so other people would contribute to it through pull requests, but at this time it seems nobody actually contributed.

https://github.com/qingfengxia/FreeCAD_Mod_Dev_Guide

Maybe at first you could write everything yourself to keep it in a single place; with good quality as you see fit, and later on move that information to the wiki.
On the topic of <br> tags - I seem to remember learning long ago that in HTML, blank lines can be more ambiguous in how they're rendered than <br> tags, and I discovered that was the case with the wiki as well. That said, I really don't like using them.
Obviously <br> tags are more precise. That's what HTML is! If we wanted ultimate precision, we would just write everything in XHTML, full of <tags> everywhere</tags>. A wiki is precisely designed to be easy to edit, compared to raw HTML.
Always add the important information to your posts if you need help. Also see Tutorials and Video tutorials.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
galou_breizh
Posts: 436
Joined: Wed Sep 15, 2010 9:38 am

Re: Scripted Object documentation

Post by galou_breizh »

Post Reply