Online source code documentation

Info about new community or project announcements, implemented features, classes, modules or APIs. Might get technical!
PLEASE DO NOT POST HELP REQUESTS OR OTHER DISCUSSIONS HERE!
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
Post Reply
User avatar
yorik
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Online source code documentation

Post by yorik »

I finally managed to reduce the size of the doxygen docs to around 500Mb, and make their appearance integrated to the rest of our web stuff, so I'm uploading it now to http://www.freecadweb.org/api/

The uploading is not finished, will take a couple of hours :) but the main pages work already.

There is still a lot of work needed on these docs to make things clearer, better group members under structures and namespaces (specially on the python side, where namespaces are automatically taken from filenames, which is not always meaningful). Nevertheless, I think these docs already do a better job than the old sphynx ones.

When building the docs, there are now two make targets: "make DevDoc", which is the original one, which is unchanged, and "make WebDoc", which produces this stripped-down version. Basically it doesn't build the graphviz schemas, which takes almost 1Gb, and it doesn't include the header files. But I managed to have the doc page include a link to the respective header and cpp files on github.

The doc will need to be rebuilt and uploaded manually from time to time, (unless one of you buildbot wizards manages to do that automatically) but it's easy enough.
User avatar
Kunda1
Veteran
Posts: 13434
Joined: Thu Jan 05, 2017 9:03 pm

Re: Online source code documentation

Post by Kunda1 »

@yorik is this at all related to issue #2303 ?

Edit: discussion about said bug can be found in viewtopic.php?f=8&t=19881
Last edited by Kunda1 on Sat Jan 14, 2017 1:30 pm, edited 2 times in total.
Alone you go faster. Together we go farther
Please mark thread [Solved]
Want to contribute back to FC? Checkout:
'good first issues' | Open TODOs and FIXMEs | How to Help FreeCAD | How to report Bugs
User avatar
yorik
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: Online source code documentation

Post by yorik »

no, not at all... That is a small embedded python server that produces automatic docs of python modules. I wonder if there is anyone actually using those?
User avatar
DeepSOIC
Veteran
Posts: 7896
Joined: Fri Aug 29, 2014 12:45 am
Location: used to be Saint-Petersburg, Russia

Re: Online source code documentation

Post by DeepSOIC »

I'm pretty sure this will come in handy! Thanks!
wmayer
Founder
Posts: 20241
Joined: Thu Feb 19, 2009 10:32 am
Contact:

Re: Online source code documentation

Post by wmayer »

I found a bug: The FreeCAD link points to http://www.freecadweb.org/api/http//www.freecadweb.org
User avatar
sliptonic
Veteran
Posts: 3457
Joined: Tue Oct 25, 2011 10:46 pm
Location: Columbia, Missouri
Contact:

Re: Online source code documentation

Post by sliptonic »

yorik wrote: There is still a lot of work needed on these docs to make things clearer, better group members under structures and namespaces (specially on the python side, where namespaces are automatically taken from filenames, which is not always meaningful). Nevertheless, I think these docs already do a better job than the old sphynx ones.
Are there any 'best practices' or examples you can point to for how to do it right?

I agree this is a big improvement :)
User avatar
yorik
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: Online source code documentation

Post by yorik »

wmayer wrote:I found a bug: The FreeCAD link points to http://www.freecadweb.org/api/http//www.freecadweb.org
Thanks! Fixing now.
sliptonic wrote:Are there any 'best practices' or examples you can point to for how to do it right?
Not really.. I'm still in the process of learning it. I would say the main point is documenting well each function and class in your code (always add a docstring). That's the principal thing to do.

Then, there are many doxygen-specific commands, that you can add in comments in your code, to do this or that. The python code in freecad uses not much of this, but most of the "core" C++ stuff in App and Gui use it extensively. The syntax is identical for both languages. There is another problem for python code, that there is no proper concept of namespace. Doxygen creates a namespace automatically from each python filename, but this is not always what we want... I didn't find a good way to handle this yet.

Anyway, there is a lot to do to improve, but basically that's what we need to do in python code: write good docstrings.
Post Reply