Online source code documentation

Info about new implemented features, classes, modules or APIs. Might get technical!
User avatar
yorik
Site Admin
Posts: 8556
Joined: Tue Feb 17, 2009 9:16 pm
Location: São Paulo, Brazil
Contact:

Online source code documentation

Postby yorik » Sun Jan 08, 2017 6:21 pm

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
Posts: 621
Joined: Thu Jan 05, 2017 9:03 pm

Re: Online source code documentation

Postby Kunda1 » Mon Jan 09, 2017 7:23 pm

@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.
User avatar
yorik
Site Admin
Posts: 8556
Joined: Tue Feb 17, 2009 9:16 pm
Location: São Paulo, Brazil
Contact:

Re: Online source code documentation

Postby yorik » Mon Jan 09, 2017 10:58 pm

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?
DeepSOIC
Posts: 4470
Joined: Fri Aug 29, 2014 12:45 am
Location: Saint-Petersburg, Russia

Re: Online source code documentation

Postby DeepSOIC » Tue Jan 10, 2017 12:02 am

yorik wrote:http://www.freecadweb.org/api/
I'm pretty sure this will come in handy! Thanks!
wmayer
Site Admin
Posts: 11227
Joined: Thu Feb 19, 2009 10:32 am

Re: Online source code documentation

Postby wmayer » Tue Jan 10, 2017 10:44 am

I found a bug: The FreeCAD link points to http://www.freecadweb.org/api/http//www.freecadweb.org
sliptonic
Posts: 594
Joined: Tue Oct 25, 2011 10:46 pm

Re: Online source code documentation

Postby sliptonic » Wed Jan 11, 2017 8:14 pm

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
Site Admin
Posts: 8556
Joined: Tue Feb 17, 2009 9:16 pm
Location: São Paulo, Brazil
Contact:

Re: Online source code documentation

Postby yorik » Fri Jan 13, 2017 6:42 pm

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.