Updates to docstrings and Sphinx rst

[crashfridh]

See branch doc on git://github.com/FRidh/FreeCAD_sf_master.git

Improved docstrings: fc8f91e99c46ff266f545cfdbc963b4c264ff99d

Updates to Sphinx documentation. Added some headings as well as new modules/classes.
cba148e04ea642ac57c402f9be8e158333568d5c

Note that Sphinx will complain that certain objects cannot be found. I haven't yet figured out what the real module is for those.


A change I haven't committed but do recommend is turning of the freecad.css in conf.py for now until the stylesheet is improved.

[yorik]

Wow, looks cool! I'll have a look asap.
Just a question, on https://github.com/FRidh/FreeCAD_sf_mas ... .doc#L3L92 looking at src/App/DocumentPy.xml on line 169, isn't that an error?

[crashfridh]

hmm, that definitely is. Keen-eyed!

I didn't get any errors when compiling this. I can push a fix for this line or I wait with it and include it when I have some more updated docstrings.

[yorik]

It's as you find better... I can merge your changes now, or if you prefer, we can wait for more. In both cases I'm happy you're working on this, it's great time we have a nice API doc!

For Werner and Jürgen, if you read this:

crashfridh's proposed changes include a series of changes to the docstrings, to make better use of sphinx's syntax. For example:

Code: Select all

<UserDocu>Remove an object from the group</UserDocu>

becomes:

Code: Select all

<UserDocu>removeObject( object )
Remove an object from the group.

:param object: object to add to the group
:type object: :class`FreeCAD.DocumentObject`
:rtype: None

</UserDocu> 

This might introduce a couple of odd characters in the FreeCAD python console's tooltips. I think it's worth doing the changes, because it will produce nice and complete API docs, and later on we can do a bit of parsing on our side to solve that, but I'd prefer to have your opinion before merging...

[crashfridh]

Could you let me know whether these changes will be merged?

[yorik]

Oh I thought you wanted to work more on this actually... Of course, I'll post here

[crashfridh]

ahh yes, I'll continue with it, though currently I have to focus on something else. Just wanted to check whether they would be included since you wanted to double check

[wmayer]

This might introduce a couple of odd characters in the FreeCAD python console's tooltips. I think it's worth doing the changes, because it will produce nice and complete API docs, and later on we can do a bit of parsing on our side to solve that, but I'd prefer to have your opinion before merging...

I don't know if possible but what about including sphinx at compile time so that it can create directly the final docstring which we then add to the .cpp file?

[crashfridh]

Right now the docstrings are written in an xml file which is included during compiling of FreeCAD. When compiling is finished, Sphinx can be called and loads the newly created Python modules. Sphinx can write output to several formats, of which one is HTML. Following your suggestion, maybe the tooltips could use the HTML created by Sphinx.

Sphinx can also build a QtHelp file. See "Using QHelpEngine API" at http://qt-project.org/doc/qt-4.8/qthelp-framework.html

Instead of showing the help in an external application like the Qt Assistant, it is also possible to embed the online help in the application. The contents can then be retrieved via the QHelpEngine class and can be displayed in nearly any form. Showing it in a QTextBrowser is probably the most common way, but embedding it in What's This help is also perfectly possible.
Retrieving help data from the file engine does not involve a lot of code. The first step is to create an instance of the help engine. Then we ask the engine for the links assigned to the identifier, in this case "MyDialog::ChangeButton". If a link was found, meaning at least one help document exists to this topic, we get the actual help contents by calling fileData() and display the document to the user.