Is there a reference manual for the complete list of the Python command in FreeCAD ?

Need help, or want to share a macro? Post here!
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
S-Y.Chen
Posts: 63
Joined: Tue Aug 27, 2019 4:33 pm

Is there a reference manual for the complete list of the Python command in FreeCAD ?

Post by S-Y.Chen »

Hi,

I am wondering is there a reference manual for the complete list of the Python command in FreeCAD ?

For example, a complete list of the Class and its Hierarchy ?

Regards
S-Y. Chen
drmacro
Veteran
Posts: 8870
Joined: Sun Mar 02, 2014 4:35 pm

Re: Is there a reference manual for the complete list of the Python command in FreeCAD ?

Post by drmacro »

in a word...no.

:cry:

But, I've started what I call a handbook.

I am (slowly) adding each function as I use or discover as I find them...it is little more than an outline at the moment. :roll:

If you care read or even to contribute:
https://github.com/macdroid53/FreeCADScripting
Star Trek II: The Wrath of Khan: Spock: "...His pattern indicates two-dimensional thinking."
heda
Veteran
Posts: 1348
Joined: Sat Dec 12, 2015 5:49 pm

Re: Is there a reference manual for the complete list of the Python command in FreeCAD ?

Post by heda »

one could argue that there is...
Untitled.png
Untitled.png (23.92 KiB) Viewed 1456 times
is it always useful, no not really, but then the place to improve should be source
you might need to seek up docs from pyside, pivy occt or any other library used as well
drmacro
Veteran
Posts: 8870
Joined: Sun Mar 02, 2014 4:35 pm

Re: Is there a reference manual for the complete list of the Python command in FreeCAD ?

Post by drmacro »

heda wrote: Fri Jun 18, 2021 3:06 pm one could argue that there is...
...

is it always useful, no not really, but then the place to improve should be source
you might need to seek up docs from pyside, pivy occt or any other library used as well
Hmm...yes, but, that is essentially just output of the docstrings. In some cases the docstrings provide enough to "guess/extrapolate" what methods, parameters, and arguments actually do/mean.

For those who have a lot of Python experience and have already have written FreeCAD Python, this may be sufficient. For the first timer, I'm guessing you might as write it in ancient Sumerian. :)

The real reason I started the handbook, is, I have a very short memory. After using some method or parameter today...six months from now my addled brain won't remember how obvious it is today. :mrgreen:

I even already forget if I added the link to @edwilliams Vector wiki to the handbook... :roll:
Star Trek II: The Wrath of Khan: Spock: "...His pattern indicates two-dimensional thinking."
heda
Veteran
Posts: 1348
Joined: Sat Dec 12, 2015 5:49 pm

Re: Is there a reference manual for the complete list of the Python command in FreeCAD ?

Post by heda »

as introduction/user guide, get your point.

as reference I prefer source doc strings, easy for coders to touch docs at the same time as the code.

an example of source docs that is would be nice if fc would start moving towards (in its own pace of course)
https://matplotlib.org/stable/api/bezier_api.html

just render with sphinx instead of pydoc would be an improvement
User avatar
onekk
Veteran
Posts: 6146
Joined: Sat Jan 17, 2015 7:48 am
Contact:

Re: Is there a reference manual for the complete list of the Python command in FreeCAD ?

Post by onekk »

Better docstrings are very welcomed, as they will improve immediately the "internal helper" in the Python Console.

For the docstring format there are two or three, (Now I don't know the exact origins) that are parsed by some python editors to have some helpers when using methods, in an IDE.

The problem, is to review much of the code and document it properly, this has some problems, as a "third person" could do the work, but if he is not the developer without some collaboration by skilled peoples, the process is error prone and maybe very bad.

It will be a good starting point for some developer discussion, but as far I remember similar discussions, about "styling code", or other "standardization" usually are blocked by the consideration that "developer are volunteers" that code for his/hers interest and you have to accept the code as is.

This is a thing that could be resolved maybe by a "FreeCAD Foundation" or similar "infrastructure", that at the moment is lacking, that could review the code additions and maybe "convince" contributor to use a "common code style" that include proper docstring and a defined format for these docstrings.

My two cents

Regards

Carlo D.
GitHub page: https://github.com/onekk/freecad-doc.
- In deep articles on FreeCAD.
- Learning how to model with scripting.
- Various other stuffs.

Blog: https://okkmkblog.wordpress.com/
heda
Veteran
Posts: 1348
Joined: Sat Dec 12, 2015 5:49 pm

Re: Is there a reference manual for the complete list of the Python command in FreeCAD ?

Post by heda »

state of affaris

doxygen (https://freecad.github.io/SourceDoc/)
source_doc_doxygen.png
source_doc_doxygen.png (118.6 KiB) Viewed 1293 times
pydoc
source_doc_pydoc.png
source_doc_pydoc.png (51.44 KiB) Viewed 1293 times
sphinx (mpl / numpydoc)
source_doc_sphinx.png
source_doc_sphinx.png (57.34 KiB) Viewed 1293 times
for the python part, at least I prefer sphinx, but suppose doxygen is needed for the c part and the benefit of pydoc is that it is a dynamic build for the actual user

don't think it would be very controversial to adapt numpydoc for fc as style for python docstrings

also don't think one have to overthink it either,
I would say any source doc is better than none, even if it is wrong, hopefully people will over time discover that it is wrong and correct it.
could even imagine that it would not be impossible to do x-links & substitution between wiki and source or vice versa (i.e. write examples in source that are pulled to wiki and rendered there)

it is a bit of one size shoe that does not fit all problem, so at least I would not mind if for example doxygen and sphinx are done in parallel, would of course require that someone is willing to nurse things, bring a full source build into reality and write some "how-to's" that others can follow.
User avatar
onekk
Veteran
Posts: 6146
Joined: Sat Jan 17, 2015 7:48 am
Contact:

Re: Is there a reference manual for the complete list of the Python command in FreeCAD ?

Post by onekk »

Oh yes, I use generally the sphinx, but I haven't take in account the C++ part.

So a standard is better than none, but as the Python Console is "built in" in FreeCAD the most viable way will be to "leverage" the Python Console "introspection" capabilities to show some "relevant" infos.

This way It will be a "good improvement" over the actual situation.

I've seen many efforts recently on improving wiki pages, so things are moving, and this is a "good new".

Regards

Carlo D.
GitHub page: https://github.com/onekk/freecad-doc.
- In deep articles on FreeCAD.
- Learning how to model with scripting.
- Various other stuffs.

Blog: https://okkmkblog.wordpress.com/
wtf_freecad
Posts: 3
Joined: Sun Mar 17, 2024 12:14 pm

Re: Is there a reference manual for the complete list of the Python command in FreeCAD ?

Post by wtf_freecad »

Hello everyone, I'm reviving these topic because I'm currently into the same problem.
Is there any doc or tutorial to create plugins and apps on FreeCad ?
heda
Veteran
Posts: 1348
Joined: Sat Dec 12, 2015 5:49 pm

Re: Is there a reference manual for the complete list of the Python command in FreeCAD ?

Post by heda »

if the question is has this improved in a meaningful manner in the last 2 yrs?
no, not really - but for fc, the question of "api-docs" is in most cases not the right question :-).

rather than using api-docs, use examples or existing code instead - and there are plenty of examples/existing code, both on the wiki as well as the forum (which is better searched on your favourite general web-search-engine).

just browsing the wiki will work as well, it has plenty of scripting info - if one searches - one will find...
if you "absorb" what is in the links on this page - Power_users_hub - you will definitely be able to do things in fc.

using the built-in console with dir() and help() is by far the easiest way for someone starting to script in fc to find api-like info on the fly.
Post Reply