Improving documentation of python API

Here's the place for discussion related to coding in FreeCAD, C++ or Python. Design, interfaces and structures.
crobar
Posts: 153
Joined: Fri Aug 29, 2014 1:26 pm

Improving documentation of python API

Postby crobar » Tue Apr 25, 2017 8:57 am

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
PrzemoF
Posts: 2533
Joined: Fri Jul 25, 2014 4:52 pm
Contact:

Re: Improving documentation of python API

Postby PrzemoF » Tue Apr 25, 2017 10:36 am

Is doxygen commenting any good for you? Like here:

https://github.com/FreeCAD/FreeCAD/blob ... emTools.py

that generates this:

https://www.freecadweb.org/api/dd/db6/c ... Tools.html
User avatar
kkremitzki
Posts: 1588
Joined: Thu Mar 03, 2016 9:52 pm
Location: Texas

Re: Improving documentation of python API

Postby kkremitzki » Tue Apr 25, 2017 11:04 am

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
Site Admin
Posts: 11263
Joined: Tue Feb 17, 2009 9:16 pm
Location: São Paulo, Brazil
Contact:

Re: Improving documentation of python API

Postby yorik » Tue Apr 25, 2017 3:51 pm

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

Re: Improving documentation of python API

Postby crobar » Tue Apr 25, 2017 4:46 pm

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
Posts: 6587
Joined: Fri Aug 29, 2014 12:45 am
Location: Saint-Petersburg, Russia

Re: Improving documentation of python API

Postby DeepSOIC » Tue Apr 25, 2017 5:43 pm

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
Posts: 4581
Joined: Thu Jan 05, 2017 9:03 pm

Re: Improving documentation of python API

Postby Kunda1 » Tue Apr 25, 2017 5:48 pm

Maybe it can be integrated in some way with the debugger WB: https://forum.freecadweb.org/viewtopic.php?f=10&t=21898
Want to contribute back to FC? Checkout:
#lowhangingfruit | Use the Source, Luke. | How to Help FreeCAD | How to report FC bugs and features
User avatar
PrzemoF
Posts: 2533
Joined: Fri Jul 25, 2014 4:52 pm
Contact:

Re: Improving documentation of python API

Postby PrzemoF » Wed Apr 26, 2017 7:36 am

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: 153
Joined: Fri Aug 29, 2014 1:26 pm

Re: Improving documentation of python API

Postby crobar » Wed Apr 26, 2017 8:57 am

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.