I would love to have an API that is PEP8 compliant when it comes to Python. However, this would break compatibility with older code. I think this could be done, eventually in a future FreeCAD 1.0 version. But of course, some aliases should be provided to help transition and avoid outright breaking everything.
Using the API
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
Be nice to others! Respect the FreeCAD code of conduct!
Re: Using the API
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.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
Re: Using the API
Not if we use fake-python modules / abstraction layers (or whatever this is called). Similar to the way we currently use PySide2 and PySide (both can be imported with "import PySide")vocx wrote: ↑Wed Nov 27, 2019 4:44 pmI would love to have an API that is PEP8 compliant when it comes to Python. However, this would break compatibility with older code. I think this could be done, eventually in a future FreeCAD 1.0 version. But of course, some aliases should be provided to help transition and avoid outright breaking everything.
Re: Using the API
Yes, this is what I mean by aliases.
Code: Select all
partOldFunction = part.new_function
Then at some point we just say, "okay, guys, starting from FreeCAD 1.0, the OldFunction no longer works, use part.new_function instead".
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.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
Re: Using the API
Yep, I know that they work. Just wanted some documentation for them and other functions I might like to use, but don't know of, yet.wmayer wrote: ↑Tue Nov 26, 2019 4:04 pm All of the mentioned functions are still available but you may have to first import the corresponding Python modulesCode: Select all
import Part import Mesh import MeshPart
Kunda1 wrote: ↑Tue Nov 26, 2019 4:32 pm Browsing API from the Python console https://forum.freecadweb.org/viewtopic. ... 33#p272495
Please demonstrate using a remote text editor to substitute the Python editor in FreeCAD https://forum.freecadweb.org/viewtopic. ... 00#p346645
Thanks for the links for reference!openBrain wrote: ↑Tue Nov 26, 2019 5:53 pm As a side note to Kunda1's above post : https://forum.freecadweb.org/viewtopic. ... 70#p333170
Sad to hear that. 5GB sounds rather big, much bigger than the FreeCAD program itself which contains documentation through the console. Do you have a source for that?vocx wrote: ↑Wed Nov 27, 2019 9:28 am This page is incomplete, https://freecadweb.org/api/.
Why? Because the entire Doxygen generated documentation is around 5 GB in size, and the developers didn't want to upload and host all that.
The incompleteness should probably better be mentioned on the API page. I expected a complete API. Regarding hosting I am rather sure there are many sites where you can host that for free. Uploading can probably also be automated. So I really hope that can be done to have a useable API available.
Sounds very promising!vocx wrote: ↑Wed Nov 27, 2019 5:31 pmYes, this is what I mean by aliases.
The OldFunction would be the legacy API, and part.new_function would be the new, PEP8 compliant API.Code: Select all
partOldFunction = part.new_function
Then at some point we just say, "okay, guys, starting from FreeCAD 1.0, the OldFunction no longer works, use part.new_function instead".
Re: Using the API
Source for what? The documentation being large? Just compile it yourself as stated in Source documentation, and then check the size.clel wrote: ↑Mon Dec 02, 2019 1:06 pm Sad to hear that. 5GB sounds rather big, much bigger than the FreeCAD program itself which contains documentation through the console. Do you have a source for that?
The incompleteness should probably better be mentioned on the API page. I expected a complete API. Regarding hosting I am rather sure there are many sites where you can host that for free. Uploading can probably also be automated. So I really hope that can be done to have a useable API available.
Doxygen generates a ton of diagrams, around 15 thousand maybe, to show the relationships between all classes in the source code.Source documentation wrote:The DevDoc target will generate a significant amount of data, around 5 GB of new files, particularly due to the diagrams created by Graphviz.
An alternative, smaller version of the documentation which takes only around 600 MB can be generated with a different target. This is the version displayed on the FreeCAD API website.
If you know how to get that free hosting, and how to automatically generate the documentation, and upload it online, then you are welcome to demonstrate that, donate such hosting space, hosting money, or whatever else is needed to improve the documentation. We don't have all this figured out. The core developers are busy doing their own things, and the rest of us, the volunteers, do what we can, but we are still shorthanded to look into every detail.
For example, qingfeng (CFD developer) decided to host the documentation himself, FreeCAD 0.19 development. I don't know if he keeps it up to date or has made improvements. Probably this should be centrally managed by the FreeCAD community and not left to one member.
This is what one lead developer says
So far it seems the core developers have managed without a complete online API because they understand the code quite well, and as long as you have downloaded the code from Git, you can always compile the documentation locally. I do agree, however, that the full online API is useful for newcomers and new programmers who would like to join the developing effort. I try my best to improve the documentation but it is still a titanic task. Fixing Doxygen Module descriptionsyorik wrote: ↑Fri Oct 26, 2018 2:09 pm ... On the other hand, we have the doxygen auto-generated pages at http://www.freecadweb.org/api which are more complete (although there is a long time I didn't update them either ) but are much less friendly to read...
We should really spend some effort in making better API docs somehow.. I wonder if there isn't some online service a la travis that could build the doxygen docs automatically and place them online for us...
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.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
Re: Using the API
In the Help menu of FreeCAD you will find the command Automatic python modules documentation where FreeCAD internally starts a little webserver that communicates with your system browser over a local socket.
Now you can browse through the available modules, classes and functions while FreeCAD generates the pages in the background. The solution is based on Python's pydoc module and thus the web pages look a bit old-fashioned but it serves its purpose.
Now you can browse through the available modules, classes and functions while FreeCAD generates the pages in the background. The solution is based on Python's pydoc module and thus the web pages look a bit old-fashioned but it serves its purpose.
Re: Using the API
Yes for the size.vocx wrote: ↑Tue Dec 03, 2019 1:50 amSource for what? The documentation being large?clel wrote: ↑Mon Dec 02, 2019 1:06 pm Sad to hear that. 5GB sounds rather big, much bigger than the FreeCAD program itself which contains documentation through the console. Do you have a source for that?
The incompleteness should probably better be mentioned on the API page. I expected a complete API. Regarding hosting I am rather sure there are many sites where you can host that for free. Uploading can probably also be automated. So I really hope that can be done to have a useable API available.
I am not so much into compiling things. But I will believe you on that not that I know that many diagrams are created. I am ok with leaving out the diagrams, that will probably give the API as it is now uploaded on the FreeCAD page. Probably the missing parts can be explained by not having wrapper classes etc. to get everything included there.
Just compile it yourself as stated in Source documentation, and then check the size.
Source documentation wrote:The DevDoc target will generate a significant amount of data, around 5 GB of new files, particularly due to the diagrams created by Graphviz.
Free hosting can probably obtained from GitHub pages for example. I am rather sure that there are other sites offering similar things for Open Source projects. A short Google search revealed at least some hosters who explicitly offer that. Also I got https://github.com/velikanov/opensource-candies which lists some free services.An alternative, smaller version of the documentation which takes only around 600 MB can be generated with a different target. This is the version displayed on the FreeCAD API website.
Doxygen generates a ton of diagrams, around 15 thousand maybe, to show the relationships between all classes in the source code.
If you know how to get that free hosting, and how to automatically generate the documentation, and upload it online, then you are welcome to demonstrate that, donate such hosting space, hosting money, or whatever else is needed to improve the documentation. We don't have all this figured out. The core developers are busy doing their own things, and the rest of us, the volunteers, do what we can, but we are still shorthanded to look into every detail.
When it comes to generation of documentation, that only was a guess. I am not sure, whether Doxygen is the best way to achieve that, I am not that much into that. However I am rather sure that it should be possible to generate documentation during an automated build and upload them to a server afterwards without human interaction needed.
Sad to see there are individual approaches. I also hope that efforts can be rather put into having some centralized and good solution.For example, qingfeng (CFD developer) decided to host the documentation himself, FreeCAD 0.19 development. I don't know if he keeps it up to date or has made improvements. Probably this should be centrally managed by the FreeCAD community and not left to one member.
Thanks for your efforts in improving the documentation! I guess currently the people with power are just too limited in time to search for such online service like travis for building documentation. The question is also, whether there is a need of a complete service or whether there can be a small script written that automatically triggers a build and then uploads the output.
This is what one lead developer saysSo far it seems the core developers have managed without a complete online API because they understand the code quite well, and as long as you have downloaded the code from Git, you can always compile the documentation locally. I do agree, however, that the full online API is useful for newcomers and new programmers who would like to join the developing effort. I try my best to improve the documentation but it is still a titanic task. Fixing Doxygen Module descriptionsyorik wrote: ↑Fri Oct 26, 2018 2:09 pm ... On the other hand, we have the doxygen auto-generated pages at http://www.freecadweb.org/api which are more complete (although there is a long time I didn't update them either ) but are much less friendly to read...
We should really spend some effort in making better API docs somehow.. I wonder if there isn't some online service a la travis that could build the doxygen docs automatically and place them online for us...
Re: Using the API
Wow! That is indeed very helpful! It is the first API I found which contained the Part.Shape() class for example. Also the documentation for functions seems to be much more complete and detailed than on Doxygen. Is there a way to get a similar complete API available hosted online? That way one could link there in Forums for reference, also Google would be able to index it, etc.wmayer wrote: ↑Tue Dec 03, 2019 12:19 pm In the Help menu of FreeCAD you will find the command Automatic python modules documentation where FreeCAD internally starts a little webserver that communicates with your system browser over a local socket.
Now you can browse through the available modules, classes and functions while FreeCAD generates the pages in the background. The solution is based on Python's pydoc module and thus the web pages look a bit old-fashioned but it serves its purpose.
Re: Using the API
Correct. The lead developers don't have a lot of time. So, if you'd like to help the project, why not investigate this yourself, and then come back with more concrete ideas and proposals?clel wrote: ↑Tue Dec 03, 2019 12:39 pm ...
I am not so much into compiling things. ...
I guess currently the people with power are just too limited in time to search for such online service like travis for building documentation. The question is also, whether there is a need of a complete service or whether there can be a small script written that automatically triggers a build and then uploads the output.
Uploading the documentation with a simple script shouldn't be a big problem, the question is how to do it in the most efficient way.
Compiling the Doxygen documentation is simple, just look at Source documentation again; it's basically two commands, cmake and make.
The best thing would be to trigger the documentation generation with every commit made to the master branch. However, this may be a bit excessive, so maybe only once per week?
Also, literally uploading the documentation (5 GB) is prohibitive. Ideally, the remote host would have the latest source code, and generate the documentation itself, so no "uploading" would be necessary, just remote compiling and hosting.
About the internal webserver that WMayer talks about, that works great for Python modules but it doesn't work perfectly for C++ libraries. Since FreeCAD is a mix of C++ sources and Python modules, it's hard to find a definite solution. Doxygen handles both, but it is best used with C++ sources. I maintain that we should build our documentation with Sphinx which is better for Python, but then it wouldn't handle C++ sources that well. In order to get C++ documentation there are some possibilities, for example, I think Sphinx can use Doxygen as a pre-processor to extract the documentation strings from C++ files. But again, this needs to be investigated and tested, and I haven't had the time to do this.
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.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
Re: Using the API
Alright. That would first require me to get known to your current build process and tools. A first easy proposal would be to use GitHub pages.
Is efficiency really such a big concern?
Uploading the documentation with a simple script shouldn't be a big problem, the question is how to do it in the most efficient way.
Assuming you do automated builds with Travis or Jenkins, that would probably rather easy? Although I have to admit that I am not very familiar with automated building.
Compiling the Doxygen documentation is simple, just look at Source documentation again; it's basically two commands, cmake and make.
The best thing would be to trigger the documentation generation with every commit made to the master branch. However, this may be a bit excessive, so maybe only once per week?
Well, one could strip the diagrams at first. But also uploading 5 GB like once a week should be ok imho. There might also be the ability to only upload the diff maybe with GitHub pages. That will probably drastically reduce the traffic.
Also, literally uploading the documentation (5 GB) is prohibitive. Ideally, the remote host would have the latest source code, and generate the documentation itself, so no "uploading" would be necessary, just remote compiling and hosting.
I got the impression that Doxygen does not contain all Python classes. Also the documentation (comments) seem to be completely missing currently. Part.Shape() for example is not listed in Doxygen. As a first step I'd be happy to see those classes and comments integrated in Doxygen. Because currently I get the impression that while Doxygen might contain the C++ code, it mostly lacks the Python API available.
About the internal webserver that WMayer talks about, that works great for Python modules but it doesn't work perfectly for C++ libraries. Since FreeCAD is a mix of C++ sources and Python modules, it's hard to find a definite solution. Doxygen handles both, but it is best used with C++ sources. I maintain that we should build our documentation with Sphinx which is better for Python, but then it wouldn't handle C++ sources that well. In order to get C++ documentation there are some possibilities, for example, I think Sphinx can use Doxygen as a pre-processor to extract the documentation strings from C++ files. But again, this needs to be investigated and tested, and I haven't had the time to do this.