m42kus wrote: ↑Thu Jun 20, 2019 6:17 pm
One thing I did yesterday was to setup a alternative version of FreeCADs doxygen documentation. Imo doxygens default configuration is a bit overloaded so I hacked together a lighter prototype. It only includes documented C++ code and is hosted on github. I did this just so I can keep track of my stuff but maybe you find something worth stealing .
Cool! Doxygen is a beast and we have quite a ways ahead of figuring out how we should document the FC code. Currently it's swiss cheese when it comes to API documentaion generated from within the code and there are mixed feelings about making the source code bloated by generating documentation this way. Maybe your approach can generate some consensus and even a convention around documenting ???
Kunda1 wrote: ↑Thu Jun 20, 2019 9:15 pm
Thanks! BTW, do you mind adding something like: Devlog: https://ceeli.github.io/gsoc/ in to your signature?
Good idea, I just added it
Kunda1 wrote: ↑Thu Jun 20, 2019 9:15 pm
Cool! Doxygen is a beast and we have quite a ways ahead of figuring out how we should document the FC code. Currently it's swiss cheese when it comes to API documentaion generated from within the code and there are mixed feelings about making the source code bloated by generating documentation this way. Maybe your approach can generate some consensus and even a convention around documenting ???
Yes the documentation is very sparse at the moment. Doxygen supports in code as well as embedding external documentation. Doing everything in the source blows up the code like you said but doing everything external is messy, hard to track and it's tedious to read the code together with the documentation. I think the best way is to combine both approaches. Documentation of members definitely belong in the source code but descriptions with examples and so on of classes, namespaces or modules could be moved out into a separate file.
Like you said the most important (and most challenging) thing is that the approach is consistently used on every part of FreeCAD. I definitely think that source documentation can't be substituted by wiki articles and if done right it's very easy to use (for both developer and user). Because writing tests is not really meaningful without stating what the function is supposed to to I'm going to write a lot of documentation. Lets see how my approach of documenting evolves during GSoC and maybe if it's received well by the community we can take parts or all of it for all of FreeCAD
m42kus wrote: ↑Fri Jun 21, 2019 9:12 am
Lets see how my approach of documenting evolves during GSoC and maybe if it's received well by the community we can take parts or all of it for all of FreeCAD
I'm looking forward to this! Thank you very much @m42kus
This week I wrote more C++ tests and documentation for the C++ module specifically for Fem::Constraint. While doing so I extended the C++ test support library further with useful tools. For details have a look at my devlog or the github repository. While looking through the code a noted a few things that don't affect the working of the workbench directly but are probably worth fixing. I wrote most of those points into notes of the source documentation. In the documentation of Fem::Constraint you find a few of these notes: https://ceeli.github.io/fcdoc/classFem_ ... raint.html.
I'm far from completing all unit tests that should be written for the modules C++ code but despite that I will move on to my next target which are python tests without GUI. The general theme for the next month will be that I try to cover as many different aspects of testing as possible. After that I should have a very good understanding of the requirements and challenges of testing all aspects of a module and I will try to combine everything into a consistent and systematic testing approach. This means of course means that I won't be able devote as much time to each aspect as it deserves but I think that the framework is much more important. I hope that if the framework is good enough we can slowly move to complete test coverage with the help of the whole community
I fixed a few issues with my code on ubuntu and tested it on Ubuntu 16.04. My testing branch should now compile on those systems without problems. No additional dependencies are required. To execute the tests I wrote just execute the FreeCADTest binary. Be sure to do a recursive clone (with submodules) because I included googletest as a submodule in the 3rdParty folder. I don't know if that is a problem for anyone. The problem is that ubuntu doesn't ship compiled google test libraries. One could use the sources from googletest-dev instead but that would require distribution specific cmake code. Including googletest in the source should work on every platform without modifications. As an alternative to a submodule we could of course just copy the code into the repository...
As of now there is no switch to turn on or off the test compilation. This is certainly on my todo list but doesn't have a high priority for now.
From my Debian packaging perspective, vendoring a copy of gtest in our source is fine, so long as there's support to use the system gtest if it's present. In Debian we can filter out unwanted copies of software that's already available in the system.
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.
kkremitzki wrote: ↑Fri Jun 28, 2019 3:09 pm
From my Debian packaging perspective, vendoring a copy of gtest in our source is fine, so long as there's support to use the system gtest if it's present. In Debian we can filter out unwanted copies of software that's already available in the system.
Hey, I don't know if debian does it differently from ubuntu but for ubuntu the recommended way of using gtest is to include it in the source. The libraries are not even available as binaries in the repositories. Do you have any experience with gtest on debian? If not I can look into it
@All There is a lot of new stuff on my devlog btw: https://ceeli.github.io/gsoc/
I'm going to write a summery in here to in the next days
Hi, just a quick status update: At the beginning of this month I progressed from writing C++ tests to writing tests for/in python. I wrote lots of documentation and tests for the femtools/femutils.py module. Right now I'm working on testing the solver framework and on a new kind of test that runs simulation and checks the results (not just if there where any errors but also if the results are what we expected e.g. displacement). I created a test support library analog to what I created for C++. You can find all of that in my testing branch: https://github.com/ceeli/FreeCAD_bhb/tree/testing.
I'm also spending a lot of time making my in source documentation appear nicely in sphinx and created a kind of sphinx prototype I'm going to share soon if you are interested. Does anyone know what the most popular opinion is for documenting python code in FreeCAD? Is it doxygen or sphinx? What I'm doing now is using sphinx with readthedocs and I combine in source documentation with pages written only for sphinx. That's of course more work than using only API documentation generation but I believe that the end result is way better. I think there is little harm in using doxygen for C++ and sphinx for python and the benefits outweigh the drawbacks (e.g. consistency).
Hi, I played around with sphinx and wrote some documentation for the FEM workbench specifically the solver framework. It's not finished but you can have a look at readthedocs: https://freecad-python-api.readthedocs. ... rview.html or https://freecad-python-api.readthedocs. ... tings.html. The other modules are empty, I just inserted them to show how it could look My experience is that sphinx works much better with python than doxygen. Doxygen works great for C++ but I found doxygen with python almost unusable. I think that the best approach would be to use doxygen for C++ and sphinx for python. I think that is done to a certain extend already but not very consistent. Honestly I am a little confused about what the current state of documentation is in FreeCAD . What do you think about that?