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?
Improving documentation of python API
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
Be nice to others! Respect the FreeCAD code of conduct!
Re: Improving documentation of python API
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
https://github.com/FreeCAD/FreeCAD/blob ... emTools.py
that generates this:
https://www.freecadweb.org/api/dd/db6/c ... Tools.html
- kkremitzki
- Veteran
- Posts: 2515
- Joined: Thu Mar 03, 2016 9:52 pm
- Location: Illinois
Re: Improving documentation of python API
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
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
Re: Improving documentation of python API
In any case, pull requests that better the doxygen docs would be highly welcome!
Re: Improving documentation of python API
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.
I find it cumbersome to go search google every time I want to know the calling syntax of a function etc.
- 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
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.
There are a few functions that are next to impossible to figure out how to use. For example, App.addDocumentObserver. Some have undocumented arguments.
Re: Improving documentation of python API
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
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
Re: Improving documentation of python API
That would be great! And we can probably extract/convert then into doxygen format if needed anyway.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.
Re: Improving documentation of python API
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
all well and good, but what do the points in the pointslist do? Obvious from other sources online, but not in the docstring.
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.