Improving documentation of python API

Here's the place for discussion related to coding in FreeCAD, C++ or Python. Design, interfaces and structures.
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
Post Reply
crobar
Posts: 160
Joined: Fri Aug 29, 2014 1:26 pm

Improving documentation of python API

Post by crobar »

I'm interested in improving the documentation of the python API. Sometimes the help provided for functions is very sparse and it is difficult to navigate using the python 'help' command. I'd like to write more detailed help for some functions using something more like the Google style for python help strings: https://google.github.io/styleguide/pyg ... s#Comments

If I do this, are pull requests for this likely to be accepted?
User avatar
kkremitzki
Veteran
Posts: 2511
Joined: Thu Mar 03, 2016 9:52 pm
Location: Illinois

Re: Improving documentation of python API

Post by kkremitzki »

BTW, the docs at freecadweb.org/api are a "lite" version because of the size of the docs with all dependency graphs, etc..

The "full"/"pretty" docs can be viewed here although they are due for a rebuild: https://docs.freecad.io

Here's an example of the same page you linked:
https://docs.freecad.io/dd/db6/classFem ... Tools.html
Like my FreeCAD work? I'd appreciate any level of support via Patreon, Liberapay, or PayPal! Read more about what I do at my blog.
User avatar
yorik
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: Improving documentation of python API

Post by yorik »

In any case, pull requests that better the doxygen docs would be highly welcome!
crobar
Posts: 160
Joined: Fri Aug 29, 2014 1:26 pm

Re: Improving documentation of python API

Post by crobar »

Well, the way I tend to work is in the interactive shell, maybe type something like Part. then look at what comes up in the tab completion, if I see a function think might do the job, say, makeLine I'll then do help (Part.makeLine) to see what it does and what the expected input/output is. The problem is, often the docstring is not very helpful, which is why I wanted to improve them.

I find it cumbersome to go search google every time I want to know the calling syntax of a function etc.
User avatar
DeepSOIC
Veteran
Posts: 7896
Joined: Fri Aug 29, 2014 12:45 am
Location: used to be Saint-Petersburg, Russia

Re: Improving documentation of python API

Post by DeepSOIC »

Yes yes, go for it.
There are a few functions that are next to impossible to figure out how to use. For example, App.addDocumentObserver. Some have undocumented arguments.
User avatar
Kunda1
Veteran
Posts: 13434
Joined: Thu Jan 05, 2017 9:03 pm

Re: Improving documentation of python API

Post by Kunda1 »

Maybe it can be integrated in some way with the debugger WB: https://forum.freecadweb.org/viewtopic.php?f=10&t=21898
Alone you go faster. Together we go farther
Please mark thread [Solved]
Want to contribute back to FC? Checkout:
'good first issues' | Open TODOs and FIXMEs | How to Help FreeCAD | How to report Bugs
User avatar
PrzemoF
Veteran
Posts: 3520
Joined: Fri Jul 25, 2014 4:52 pm
Contact:

Re: Improving documentation of python API

Post by PrzemoF »

crobar wrote:Well, the way I tend to work is in the interactive shell, maybe type something like Part. then look at what comes up in the tab completion, if I see a function think might do the job, say, makeLine I'll then do help (Part.makeLine) to see what it does and what the expected input/output is. The problem is, often the docstring is not very helpful, which is why I wanted to improve them.

I find it cumbersome to go search google every time I want to know the calling syntax of a function etc.
That would be great! And we can probably extract/convert then into doxygen format if needed anyway.
crobar
Posts: 160
Joined: Fri Aug 29, 2014 1:26 pm

Re: Improving documentation of python API

Post by crobar »

ok, well I'll probably start doing this, but it will be gradual, as I come up against things I can't understand from the docstring, a first candidate is probably Draft makeBezCurve. The string is

Code: Select all

makeBezCurve(pointslist, closed=False, placement=None, face=True, support=None, Degree=None)
    makeBezCurve(pointslist,[closed],[placement]): Creates a Bezier Curve object
    from the given list of vectors.   Instead of a pointslist, you can also pass a Part Wire.
all well and good, but what do the points in the pointslist do? Obvious from other sources online, but not in the docstring.
Post Reply