BCF Support GSoC Proposal
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
Be nice to others! Respect the FreeCAD code of conduct!
Re: BCF Support GSoC Proposal
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.
Re: BCF Support GSoC Proposal
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.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).
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.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 ) 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 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
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.And then there are tutorials, which I know of, because used one of them to get a hold of the FEM workbench ^^
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.
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.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
Re: BCF Support GSoC Proposal
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!
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!
Re: BCF Support GSoC Proposal
Other BCF discussion I had forgotten about: https://forum.freecadweb.org/viewtopic.php?p=302043
Re: BCF Support GSoC Proposal
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):
Cheers,
Patrick
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):
- Work through the QTDesigner, in which I will design the frontend of the plugin
- Create a mock-up design of the plugin, with a meticulous description of the functions that it shall support and in what way
- Walk through the PySide tutorials on https://www.freecadweb.org/wiki/PySide
- Dive deep into the plugin Yorik developed to get a grasp on how plugins integrate into FreeCAD
- At last I will gather some existing BCF examples that serve as a starting point for development.
Cheers,
Patrick
Re: BCF Support GSoC Proposal
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:
(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:
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:
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.
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
Code: Select all
BCF.openViewer()
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()
- duncan.lithgow
- Posts: 42
- Joined: Sat Jan 11, 2014 6:29 pm
- Location: Denmark
- Contact:
Re: BCF Support GSoC Proposal
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.
- hardeeprai
- Posts: 177
- Joined: Sun May 23, 2010 2:41 pm
- Location: Ludhiana, Punjab, India
- Contact:
Re: BCF Support GSoC Proposal
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.
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.
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
H.S.Rai
- duncan.lithgow
- Posts: 42
- Joined: Sat Jan 11, 2014 6:29 pm
- Location: Denmark
- Contact:
Re: BCF Support GSoC Proposal
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
https://github.com/teocomi
Re: BCF Support GSoC Proposal
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.
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).hardeeprai wrote: ↑Wed May 08, 2019 10:51 pm ...
Do you have any exposure / experience, as a user, of any other BCF software?
...
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?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.
Also thank you for bringing up Matteo Cominetti, probably I will probably have one two questions for him