Improve the FreeCAD API documentation

[yorikvanhavre]

Outline

Work on the FreeCAD doxygen-generated documentation: Propose a better plan, document the modules better, make it clearer to read, etc.

Details

The API documentaiton of FreeCAD is generated with doxygen from the docstrings contained in the source code. It is hosted on https://github.com/FreeCAD/SourceDoc . It is currently not easily readable, the modules structure doesn't list classes and functions, python functionality is not well distinguishable from C++ functionality, and many other problems.

Expected Outcome

Identify problems and possible solutions, and propose changes to the docstrings and in-source doxygen instructions to build better docs, and possibly do some css work to produce a cleaner HTML result

Project Properties

Skills

The student should have or build a good knowledge of doxygen, optionally be ready to do some css work too

Difficulty

Medium

Additional Information

• Potential mentor(s): Yorik
• Organization website: https://freecad.org
• Communication channels: https://https://forum.freecad.org

[Ovalelephant35]

Thankyou sir @yorikvanhavre for prompting me here , i have read the problem statement and also have gotten a fade idea of what is needed , though if you can guide me towards starting point and more documentation which i can read and understand and learn it will be really helpful.
Also what i have understood till now is there is lack of clearity and also it is very difficult to distinguish between python and cpp functions ,classes etc , i guess i would like to start with understanding overall codestrucutre of freecad .
i guess we need Improved Structuring of Documentation and Clearer Distinction between Python and C++ Functionality ,Standardized Documentation Format and feedback mechanism etc to start with

[tobiasfalk]

This sounds like a good Idea, a while back I already complained about the general lack of Documentation in TD WB(https://forum.freecad.org/viewtopic.php?p=694678#p694678).

[Ovalelephant35]

@mentors Should we also make readme more informative aswell by seperating commands and there purpose and also giving more specifics in readme only rather then hyperlinking it to another page as it will be more approachable and informative that way also what can be idea for document structure like what is generally preferred Thankyou.

[Ovalelephant35]

Also the names etc arent also informative either they are autogenerated / hashed or encoded and also making a proper directory like structure and making it human readable will also be good idea does it sound good ?

[yorikvanhavre]

You got it quite right @Ovalelephant35 . The problems I see:

• Doxygen docstrings are not enough used and not standardized througout the code. They should be improved, and probably a very large part of the work needed here is that: Going through the code, and write better strings

• C++ and Pyton docs are indeed mixed, and this is bad. It turns both unusable. C++ users and Pytohn users have pretty different requirements.

• C++ users are usually experienced coders. They need to go straight to the point. They want basically a cleanly "rendered" version of the .h files, and understand the whole code structure clearly (what needs to be included, what are the namespace domains, etc). They don't want to see the Python part

• Python users are often beginners or people with little coding experience. They would want to see the API in a much simpler, descriptive manner. They need to see more text, and less structure. They don't want to see the C++ part

• Somehow, it should be possible to build two different targets: C++ and Python. Maybe there's a possibility to "mark" what should go in what target?

• We're in the process of migrating the FreeCAD documentation to a markdown-based format. The Python API docs could ideally at some point become part of that markdown documentation. That's something to think about for the future

That's all I have at the moment... I suggest you look a bit further at the code, you'll probably get more ideas of what could be done

[RohanMishra315]

Hi @yorikvanhavre Rohan here , from past 2-3 months I have been contributing to FreeCad and been an active member. I had worked on many good first issues and features request and some of my work based on documentation you can look at here , https://github.com/RohanMishra315 .

I am interested in working on the FreeCAD Doxygen Documentation Improvement Project to further contribute to the enhancement of FreeCAD's documentation. Based on the identified problems and proposed solutions, I plan to:

Conduct a thorough analysis of the existing codebase to identify areas where doxygen docstrings can be improved and documentation for C++ and Python users can be separated.
Work on improving existing doxygen docstrings to ensure they are comprehensive, standardized, and meet the needs of both C++ and Python users.
Implement mechanisms to separate documentation for C++ and Python users, such as annotations or tags, and configure doxygen to generate separate documentation targets.
Explore integration possibilities with the markdown-based documentation being migrated, and propose strategies for integrating and maintaining Python API documentation within the markdown documentation structure.
Looking forward to discuss more with you !

[Ovalelephant35]

I have started to classify different files and classes and functions based on there utilities also have understood that main gap lies in the fact that standardisation of doxygen strings being not used uniformly.
The best approach i think as of now and i am working on is :- directory method classifying each classes and there usecase and then segregating them in based on python and cpp users also as stated that cpp user dont need as much detailed info will make them crisp and python one quite detailed.
though as size is quite large of the files what would be according to you high priority task where should we have the entry point @yorikvanhavre also as soon as we can apply changes and see things it will give more and more clearity??

[Ovalelephant35]

This you can see i have devised a fade idea on how final directory should like also making it more easy to transfer it markdown format later.

[Ovalelephant35]

Currently Understanding codebase as well as understanding on how different part of modules has to be catered and differentiated as well as working on related codebases also thankyou.

[yorikvanhavre]

Glad to see you guys interested in working on this. Go through the code at ease, the more you go and read the better you'll understand the problem. Also, I would have a look at other open-source projects and try to find good examples of good C++ and good Python documentation. Some good ones I have out of my mind are:

• the coin docs https://www.coin3d.org/Coin/html/ becasue it's clean, complete and easy to browse (and also doxygen-based)
• the qt docs https://doc.qt.io/qt-6/qobject.html it's totally another concept, but it's very clean and elegant, and has a LOT of info including code examples. Maybe a good example of how Python docs should look like?

Also, if several of you will want to propose to work on a same idea, remember we'll only be able to choose one. But it's also totally possible to submit more than one proposal.

[Ovalelephant35]

well to be honest qt docs are really very elegant and also its quite engaging as well , also coin docs is almost similar to ours only difference being as you have already stated its easy to browse so like if we are thinking of python to be in md format then is it possible to segregate them completely like completely 2 docs or what do you think what should be plan of action.

[Ovalelephant35]

Also regarding the entry point as i asked earlier as source doc is quite large where should i start exactly like is there any priority involved @yorikvanhavre.

[tobiasfalk]

Qt definitely has a very good documentation style and it would not be harmful to have some of it also in the C++ documentation.

An other example for Documentation could be Boost and and CPPRef.

I personally think a start would be a Style guid for the documentation, so that work dous not have to be done twice. This should include WHAT and HOW documentation is to be done, examples for the various classes, functions, variables and everything else. But it would also be nice if it would include formulation help and templates to make it easier and more streamlined.
This would also help with making it more uniform.

[Ovalelephant35]

@tobiasfalk yes makes complete sense and CPPRef is quite informative , uniform and elegant in compact space it seems a good design specifically for CPP people.
Ok let me see if i can found more design and try to implement ours and understand there flow and uniformity.

[tobiasfalk]

Sorry🤦‍♂️

An other place that came to my minde would be the Microsoft code Documentation, rather good and informative, but other quite detailed.

[Ovalelephant35]

Well the thing is documentation is largely subjective to different people https://github.com/Ovalelephant35 like in all the repo i make i make sure to include as much detail as possible but at the same time is needed to be changed again and again accordingly as circumstances demand

[Ovalelephant35]

So the more discussion we will have large perpective we can get leading to better documenting the documentation process😅

[Ovalelephant35]

I have been using Freecad for a year now started to use it for my Engineering Graphics course , also have been part of generally Cpp community so let me start with that only and make prototype similar somewhat similar to CPPref and let see if makes sense @yorikvanhavre @tobiasfalk .

[Ovalelephant35]

This you can see i have devised a fade idea on how final directory should like also making it more easy to transfer it markdown format later.

i will be follwing this directory structure.

[Ovalelephant35]

Just trying in html , doxygen on some files currently following qt though will give more mock ups etc and will also move on to improving docstrings also

[Ovalelephant35]

@ mentorss @yorikvanhavre moreover i was thinking of following qt only as of now though as i said earlier more ideas always welcomed

[Ovalelephant35]

Also there is pdf also generated though are they of any use or like is it stored here or they can be ignored? @ mentors
And wanted to ask though this can be done later like we should also make proper readme file on how to write comments , strings etc so that they are uniform throughout or like is it already available?

[yorikvanhavre]

Nice screenshot! :)

I don't think pdf output is important, I doubt anybody would want to print that :) If you find that a better scope, you could propose to only take care of the C++ part, no problem with that.

This page can help giving you a broad understanding of how the code is structured: https://wiki.freecad.org/The_FreeCAD_source_code

[Ovalelephant35]

Thankyou for Replying , yes pdf output can be just available as a downloadable material , no need to worry about it ig because it can obtained anytime.
Yes c++ part is what i have started with its just that , there is no issue from my side regarding python only reason i am treating them separately is so that proper differentiation could be maintained and its easy for me/anyone in future to deploy then further in markdown format later.

First of all thank you And also screenshot should be taken as pinch of salt i was trying out mockups and just understanding cmake , styling , filing , organizing format of doxygen and its interaction will come up with more better oriented mockups in days .

Thanks @yorikvanhavre for the link also other links that have been provided i have been monitoring them closely to get as much idea as i can

[Ovalelephant35]

Very Basic and rudimentary level diagram, understanding how logic should work and interactions between different elements with commands should happen , we can also link CSS files as well , furthermore we can implement standard conduct so that all the comments could be easily parsed and each of modules , classes could be clear i am also working on some mockups as well but currently my main aim is to grasp on more and more codebase so that formalization can be done , also @yorikvanhavre @ mentors can you suggest regarding how should we actually we should store source code developed by doxygen from Freecad/ freecad codebase like currently it is as a repo but are there more ideas or should we continue with that.

[Ovalelephant35]

@yorikvanhavre I think we can continue with current way repo is stored only but i think we can have a very nice nomeclature of each file and directory in our source code also this will lead to easier distinction as well as it will be way more readable and it can be achieved by using doxyfile and some snippets like these

HTML_FILE_EXTENSION    = .html
HTML_MAIN_PAGE         = index
HTML_HEADER            = custom_header.html
HTML_FOOTER            = custom_footer.html

Something like this will give us the desired result in https://github.com/FreeCAD/SourceDoc

[Ovalelephant35]

Anything you have to add also like more ideas / if anything i am doing incorrectly or you want the other way @yorikvanhavre sir?

[yorikvanhavre]

This looks very good! I added some comments on your PR, basically I don't think you should remove anything, unless for a good reason (ex. it's wrong). Otherwise, the doc strings you added are perfect, I think that's the kind of thing we sorely need!

[Ovalelephant35]

Thankyou for review, what currently i am trying to do is to go through each of docs and seeing for missing files/api documentation and adding in parallel to working on docstring and I will only add or correct stuff only from my part thats for sure without removing or disturbing anything all ready there i dont know why it happened with shapefix file to me it was completely empty of documentation thats why i added otherwise i myself want them to be as much descriptive as possible because information any day comes first.

[Ovalelephant35]

@yorikvanhavre I have made another PR on missing docs and checked twice it only adds values also I will be sharing my GSOC detailed Proposal ,I will be obliged if you can review it.
Thankyou.

[Ovalelephant35]

Hi , @yorikvanhavre this is my final draft for this project kindly review.
FreeCAD_Oval.pdf

Pre-GSoC Activity: Begin intensive exploration of the FreeCAD codebase from April 3rd.
Proposal Ranking: Organizations can rank proposals starting April 24th.
Community Bonding: Engage in refining mockups and optimizing ideas with mentors during the community bonding period starting May 1st.
Official Coding Period: Dive into active coding and contributions to FreeCAD starting May 27th.
Eagerly anticipating the opportunity to be part of the FreeCAD project this summer.
Thank you!
Anurag Singh (Ovalelephant35) <3.

[Ovalelephant35]

@yorikvanhavre
FreeCAD_Oval.docx - docs
FreeCAD_Oval.odt - Odt

[yorikvanhavre]

Sorry for the delay @Ovalelephant35 ok, your proposal sounds good!

[Ovalelephant35]

Thankyou !! Well delay was from my side initially, due to some unseen circumstances. Though I have submitted the detailed proposal on GSOC official site with all the work I will be doing.
I am open to any changes / ideas or any new modification as per requirements, review and feedback and as I mentioned in proposal for pre GSOC activity from april 2nd to may 28th I will be devoting my time on this only before coding period begins.
Thanks again for your time @yorikvanhavre and reviewing my proposal.

[Ovalelephant35]

Hi, @yorikvanhavre !
Some Updates.

1. I've reviewed most of our codebase and updated some of the missing documentation. While all the intended API documentation exists in the XML files, many of these are poorly written. Would you like me to rewrite them to improve clarity before the official coding period starts? If so, do you have a preferred format? For example, should I include detailed descriptions of the arguments and other key information?
2. I've tested nearly all the mockups based on the provided links and created a few additional ones, all of which are included in my proposal. After testing, I've gained some valuable insights. The documentation styles from both Coin and QT are solid, but I'm leaning towards Coin's style because it's more clear, concise, and developer-friendly. I'd like to know your thoughts on this approach!
3. I've created and tested a variety of docstrings, which I've detailed in my proposal and mentioned in previous messages. This part of the project can now be completed with ease. I've gained a lot of valuable insights, which can be used to maximize the potential of both the design and documentation. However, there are still some aspects that need further exploration. I plan to address those before the official coding period begins.
4. I'd like to start with documenting the C++ code, and later we could focus on the Python API documentation. This approach allows us to address the C++ documentation needs first, with the flexibility to move on to Python later also making it easier for its deployment in markdown format. And yes it is possible to focus on both of them and achieve desire target. How does this plan sound to you?

"That wraps up the major planning and testing homework. Now, all that's left is execution, along with some additional testing and planning from point 3. I'm really excited to start working on this and make the API documentation the best it can be! 😁

[yorikvanhavre]

Heard you got selected on another GSoC project @Ovalelephant35 , good luck to you there! Feel free to come help us with the API docs later on if you fancy! (Also, keep in mind we have our own funding program) ;)

[Ovalelephant35]

Hi @yorikvanhavre , I have already made up my mind, I will be completing all the work according to the timeline I provided.
Also thanks for letting me know about funding Program, let me go through it once and see if I can do anything about it.
Thanks.

[furgo16]

If I understand it correctly, looking at https://summerofcode.withgoogle.com/programs/2024/projects it seems that this particular project "Improve the FreeCAD API documentation" will not be part of GSoC 2024, correct?

[yorikvanhavre]

If I understand it correctly, looking at https://summerofcode.withgoogle.com/programs/2024/projects it seems that this particular project "Improve the FreeCAD API documentation" will not be part of GSoC 2024, correct?

Correct! We have two GSoC projects this year: https://forum.freecad.org/viewtopic.php?p=756812#p756812