Using the API

[vocx]

... I guess we first need to define policies for the API which includes (Gui vs App handling, naming conventions, import-conventions, ...)

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.

[looo]

... I guess we first need to define policies for the API which includes (Gui vs App handling, naming conventions, import-conventions, ...)

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.

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]

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")

Yes, this is what I mean by aliases.

Code: Select all

partOldFunction = part.new_function

The OldFunction would be the legacy API, and part.new_function would be the new, PEP8 compliant API.

Then at some point we just say, "okay, guys, starting from FreeCAD 1.0, the OldFunction no longer works, use part.new_function instead".

[clel]

All of the mentioned functions are still available but you may have to first import the corresponding Python modules

Code: Select all

import Part
import Mesh
import MeshPart

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.

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

As a side note to Kunda1's above post : https://forum.freecadweb.org/viewtopic. ... 70#p333170

Thanks for the links for reference!

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.

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.

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")

Yes, this is what I mean by aliases.

Code: Select all

partOldFunction = part.new_function

The OldFunction would be the legacy API, and part.new_function would be the new, PEP8 compliant API.

Then at some point we just say, "okay, guys, starting from FreeCAD 1.0, the OldFunction no longer works, use part.new_function instead".

Sounds very promising!

[vocx]

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.

Source for what? The documentation being large? Just compile it yourself as stated in Source documentation, and then check the size.

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.

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.

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

... 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...

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 descriptions

[wmayer]

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.

[clel]

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.

Source for what? The documentation being large?

Yes for the size.

Just compile it yourself as stated in Source documentation, and then check the size.

The DevDoc target will generate a significant amount of data, around 5 GB of new files, particularly due to the diagrams created by Graphviz.

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.

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.

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.

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.

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.

Sad to see there are individual approaches. I also hope that efforts can be rather put into having some centralized and good solution.

This is what one lead developer says

... 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...

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 descriptions

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.

[clel]

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.

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.

[vocx]

...
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.

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?

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.

[clel]

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?

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.

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.

Is efficiency really such a big concern?

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?

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.

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.

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.

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.

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.