BCF Support GSoC Proposal

Contributions from the participants, questions and answers to their projects.
Discussions of proposals for upcoming events.
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
User avatar
yorik
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: BCF Support GSoC Proposal

Post by yorik »

That seems perfect! It doesn't matter much. You can write everything on github and "self-host" the documentation yourself, or write it on the FreeCAD wiki, as you prefer (no need to decide now either). The important is to have the documentation, not really where or how it is produced and hosted. At this point the important point is to plan to dedicate some time to producing good docs.
vocx
Veteran
Posts: 5197
Joined: Thu Oct 18, 2018 9:18 pm

Re: BCF Support GSoC Proposal

Post by vocx »

pPodest wrote: Sun Apr 07, 2019 6:23 am ...
How is the documentation style currently in FreeCAD? Till now I only looked a bit into the FEM workbench, which does not give the whole picture. I reckon that much of the code is documented in doxygen style (or something similar) that can be parsed in a nice format (like html or pdf in case of doxygen).
Allow me to be blunt on this. The documentation style of FreeCAD is a mess! Simply put. The original developers didn't exactly care too much about documenting everything in an accessible way, and I believe this is an issue when it comes to making it easy for others to join in extending FreeCAD. Simply put, there isn't enough description of the core components of FreeCAD. As long as nobody touches it, and it works, then people will just build workbenches on top.
yorik wrote: Fri Oct 26, 2018 2:09 pm We have actually a problem here: The API wiki pages are created manually, and yes, indeed they are almost all out of sync with current version. 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 :oops: ) 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...
The API pages (Builtin modules) that you see in the wiki were manually created. Yes, the classes and functions were taken from the source code, and placed in the wiki, and small descriptions were written. As you can imagine, now these pages are probably outdated.

The Doxygen autogenerated API documentation is supposed to solve this issue and keep the FreeCAD code documentation up to date. But for this to work well, every single piece of code needs to be correctly commented in the source code itself, and this is what is currently missing.

I believe one of the best efforts at documenting FreeCAD is a book, written in chapters, by Qinfeng Xia, who is also the developer of the Cfd workbench for computational fluid dynamics. He decided to write that book around 3 years ago, to serve as a guide for aspiring developers who wanted to create a new workbench. https://github.com/qingfengxia/FreeCAD_Mod_Dev_Guide

He purposefully placed it in github so that other developers would contribute to the book, helping to extend it, and keeping it up to date. However, I don't know if anybody has touched it in years, so the information contained there may already be somewhat obsolete.

Also, he built his own Doxygen documentation, which in some ways looks better than the current one http://www.iesensor.com/FreeCADDoc/0.16-dev/index.html
And then there are tutorials, which I know of, because used one of them to get a hold of the FEM workbench ^^
What really exists in FreeCAD is end user documentation. Many people over the years have used FreeCAD, have learned tricks to use the software better, and have written about it in a multitude of forum posts and code snippets. But all this experience is still not very well condensed in the "official" documentation, which is supposed to be based on the wiki.

So, my advice is this: document everything very well in the source code. Even if you think it's obvious or overboard, it will help a lot for the future programmers that will look at your code. If you don't document the code, at least provide good documentation for the user in the form of good command descriptions and tutorials. I personally went into the Draft Workbench wiki pages, and added a ton of information to each tool, like Draft Wire, Draft Dimension, etc. I went to the source code, read it to understand what the tool did, and added the information to the wiki. A lot of that information could be automatically generated from the source itself, if the source was correctly commented and up to date. So, comment your code well, and you'll have both good programming and user documentation.
pPodest wrote: Sun Apr 07, 2019 4:37 pm If the current style of code documetation is pdoc then I do not want to dance out of line with suddenly doxygen.
yorik wrote: Mon Apr 08, 2019 2:20 pm The important is to have the documentation, not really where or how it is produced and hosted.
The reason Yorik basically says "do whatever you want" is precisely because there is no overall standard guideline for the documentation. You can do whatever you want! It's a mess! This is not a knock on Yorik. He's the one keeping FreeCAD thriving, but it's basically the reality. At this point in time FreeCAD is still a growing project so it seems most people favor a quick development pace, and don't worry too much with boring stuff; you guessed it, documentation!

I personally suggest you to use Python guidelines (pdoc, PEP8, look at the documentation of numpy, matplotlib, etc.) to document Python code, and worry about Doxygen another time. The FEM Python coding standard seems sensible to me.

(Hint: I wished you'd make a second proposal to GSoC to organize FreeCAD's documentation, and refactor modules to a more Pythonic standard.)
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.
User avatar
pPodest
Posts: 71
Joined: Sat Feb 16, 2019 3:18 pm

Re: BCF Support GSoC Proposal

Post by pPodest »

Wow! Thank you @vocx for that elaborate explanation of the current documentation situation in FreeCAD. I can understand why you would have liked it if I had proposed a second project, in which I would work on the documentation.

However that takes some pressure off my shoulders. Maybe through working with FreeCAD I gain other valuable insights that are little documented. If time allows I will extend it, to help a little more than planned in my proposal :).

To all mentors that might read this post: I wish you much fun selecting some proposals, there will certainly be very good ideas from my colleagues!
User avatar
yorik
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: BCF Support GSoC Proposal

Post by yorik »

Other BCF discussion I had forgotten about: https://forum.freecadweb.org/viewtopic.php?p=302043
User avatar
pPodest
Posts: 71
Joined: Sat Feb 16, 2019 3:18 pm

Re: BCF Support GSoC Proposal

Post by pPodest »

Hi all,

so since my project proposal became an actual project in GSoC this thread will become more active again.
Currently the community bonding period is still in effect which is a perfect opportunity to hear from as many people as possible and possibly gather some ideas and suggestions that make the outcome of the project better.

For all that didn't read the project proposal, here is a short version of what it is about:
BCF (BIM Collaboration Format) is, as the expanded name suggests, a collaboration format that shall make it rather easy to communicate topics/issues within a model of, let's say, a building. It offers some really nice features, as I learned, like leaving comments which have viewpoints attached so the user not only can read the comment, but also view the model from the perspective the creator viewed it while writing. This project is aimed at incorporating support for the BCFormat into FreeCAD.

Currently I plan to let an independent plugin be the output of the project, as suggested by Yorik here.
Thanks to Yorik and Bernd and their suggestions, I created a plan for the bonding period which I will also post here (just for information):
  1. Work through the QTDesigner, in which I will design the frontend of the plugin
  2. Create a mock-up design of the plugin, with a meticulous description of the functions that it shall support and in what way
  3. Walk through the PySide tutorials on https://www.freecadweb.org/wiki/PySide
  4. Dive deep into the plugin Yorik developed to get a grasp on how plugins integrate into FreeCAD
  5. At last I will gather some existing BCF examples that serve as a starting point for development.
So this is what I envision to do the next few weeks! Are there already some suggestions/wishes (for features or the documentation) that I shall consider early on? :)


Cheers,
Patrick
User avatar
yorik
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: BCF Support GSoC Proposal

Post by yorik »

Looks good!
Additional comment, for you to think of the general structure:

A "plugin" in FreeCAD is a vast concept. There is a large number of ways you can do that. In a sense, all of FreeCAD workbenches are plugins. A simple 5-lines python script, that you can run from the Macros menu or simply from the python console, is also a plugin. There is basically no difference between the two regarding their powers and what you can achieve with them.

So I would rather think to your project as a python module. It can be a single-file script of multiple files in a directory, that's up to you. But it would basically work as a python module, that is, from the FreeCAD console, you'd be able to do this:

Code: Select all

import BCF
(or whatever you decide to call it), and from there, call any of its functions. I suppose there would be basically a main one that would launches the viewer UI. Something like:

Code: Select all

BCF.openViewer()
Integrating your module inside the FreeCAD UI would then be very simple, it would be just a button that executes these 2 lines of code. All the rest happens inside your module.

That's basically where you should aim at. You could add more stuff in the BCF module, that would be useful to python coders (I encourage you a lot to make a pure-python function equivalent for everything that can be done via the UI, so other python coders can use your module in other areas). I imagine something like this:

Code: Select all

bcf = BCF.open(filename)
bcf.Issues
my_issue = bcf.Issues[5]
my_issue.Comments
my_comment = my_issue.Comments[3]
my_comment.Author
my_issue.addComment("Yorik","Look at this issue, Bernd!!")
bcf.save()
In fact I encourage you to spend some time designing this first, think python only. Then, your UI work will be greatly simplified, basically each button or control will simply execute a corresponding python function.
User avatar
duncan.lithgow
Posts: 42
Joined: Sat Jan 11, 2014 6:29 pm
Location: Denmark
Contact:

Re: BCF Support GSoC Proposal

Post by duncan.lithgow »

Congratulations on getting your proposal accepted. I'll try and do what I can to help with my knowledge of BCF - I'm planning to spend some of my week 30 summer holiday learning python.
User avatar
hardeeprai
Posts: 177
Joined: Sun May 23, 2010 2:41 pm
Location: Ludhiana, Punjab, India
Contact:

Re: BCF Support GSoC Proposal

Post by hardeeprai »

pPodest wrote: Wed May 08, 2019 1:19 pmso since my project proposal became an actual project in GSoC
Congratulations!

You deserved it. Hope, the outcome of this project will further strengthen FreeCAD's position in BIM field, and at the same time you will have fun.

pPodest wrote: Wed May 08, 2019 1:19 pmthis thread will become more active again.
It should. Communication is the key factor in, in general, in FOSS and in particular in GSoC. Whatever you are thinking, possible alternatives, needed to share.

pPodest wrote: Wed May 08, 2019 1:19 pmCurrently the community bonding period is still in effect which is a perfect opportunity to hear from as many people as possible and possibly gather some ideas and suggestions that make the outcome of the project better.
Do you have any exposure / experience, as a user, of any other BCF software?

Wish you all the best for GSoC and expect your long term association with FreeCAD.
--
H.S.Rai
User avatar
duncan.lithgow
Posts: 42
Joined: Sat Jan 11, 2014 6:29 pm
Location: Denmark
Contact:

Re: BCF Support GSoC Proposal

Post by duncan.lithgow »

I you haven't already I suggest you plan to make contact with Matteo Cominetti (teocomi) author of the GNU BCFier plugin to Revit and standalone viewer. He's a helpful and approachable guy who is sure to have some valuable insights into implementing BCF.

https://github.com/teocomi
User avatar
pPodest
Posts: 71
Joined: Sat Feb 16, 2019 3:18 pm

Re: BCF Support GSoC Proposal

Post by pPodest »

yorik wrote: Wed May 08, 2019 2:44 pm ...
In fact I encourage you to spend some time designing this first, think python only. Then, your UI work will be greatly simplified, basically each button or control will simply execute a corresponding python function.
Ok thank you for this early suggestion. I would have probably gone the other way around, but after thinking about it python interface first seems to be better.

From what I know by now about BCF and the features it supports, it will be quite hard to create a simple interface that covers all of them. I will look into other programs and how they designed their UI and on what they put the emphasis on.
hardeeprai wrote: Wed May 08, 2019 10:51 pm ...
Do you have any exposure / experience, as a user, of any other BCF software?
...
No, not really unfortunately. I only checked out the BCF definition, which gave me my initial ideas about the design of the UI (in my proposal).
duncan.lithgow wrote: Wed May 08, 2019 5:53 pm Congratulations on getting your proposal accepted. I'll try and do what I can to help with my knowledge of BCF - I'm planning to spend some of my week 30 summer holiday learning python.
Thank you Duncan! Did you already work with BCF software extensively? If so did you already experience some pain points (i.e. stuff that was implemented in a bad way) and wish that these points are done better in this project?
Also thank you for bringing up Matteo Cominetti, probably I will probably have one two questions for him :)
Post Reply