wiki2qhelp.py failed to build a valid qhc & qch

Here's the place for discussion related to coding in FreeCAD, C++ or Python. Design, interfaces and structures.
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
User avatar
jriegel
Founder
Posts: 3369
Joined: Sun Feb 15, 2009 5:29 pm
Location: Ulm, Germany
Contact:

Re: wiki2qhelp.py failed to build a valid qhc & qch

Post by jriegel »

Ok, but then I would do it completely.
Start with the FreeCAD gui a little http web-server on some obscure port (4711) and deliver all the
off-line stuff (python help, user help....) with the same technologies as on the web (HTML5 and JavaScript).
That would allow us to install all kind of docu and other stuff in the www-root of the the local FreeCAD webserver
and we would have not to deal with all kind of special stuff like qch and so on....
each module can also install reload and generate its own reporting and documentation.

As more as I think about it, the more I like it ;)
Stop whining - start coding!
User avatar
yorik
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: wiki2qhelp.py failed to build a valid qhc & qch

Post by yorik »

Sure. This is what I did so far:

1) install python-sphinx
2) make a doc folder (I used the doc folder in my cmake build folder, just to test. But I think it can be done directly in the source tree without problems)
3) run sphinx-quickstart, answer defaults, make sure to say "yes" about autodoc
4) edit index.rst, add a couple of modules to the contents:

Code: Select all

Contents:

.. toctree::
   :maxdepth: 2

.. automodule:: FreeCAD
   :members:

.. automodule:: FreeCADGui
   :members:
5) edit conf.py, add

Code: Select all

sys.path.append('/home/yorik/Apps/FreeCAD/lib/')
after import sys
6) run "make html"
7) you then have an index.html file in _build folder.

Instead of adding automodules to the index page, the correct behaviour would be to create one separate .rst file for each module, then link them in the index page. The alteration in conf.py is needed so sphinx can find the FreeCAD module (the autodoc features just does an "import ModuleName"). If you also add "import FreeCAD", then all module paths are added as well, which is handy.

What would be cool is to integrate this tightly with our wiki, like the blender people did. I didn't investigate much yet, but it might be simple (using the wiki CSS for example)
wmayer
Founder
Posts: 20241
Joined: Thu Feb 19, 2009 10:32 am
Contact:

Re: wiki2qhelp.py failed to build a valid qhc & qch

Post by wmayer »

Great! Thank you!
User avatar
yorik
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: wiki2qhelp.py failed to build a valid qhc & qch

Post by yorik »

A little bit of CSS later...

Image

I think this can give very cool results... Even if it is not "embeddable" in the wiki, we could host that somewhere else (I think SF allows to upload plain html somewhere...) and link seamlessly inside the wiki. It would then just be a matter of generating and uploading the html files manually from time to time, but at this point that would not be too much problem.

A couple of further things I discovered with sphinx:
  • - Instead of putting everything inside the index.rst, better do one .rst per module. This will create one separate page for each module
  • - all the css, images and other stuff must simply be in the _static folder, then add in the conf.py (html_style = 'freecad.css')
  • - I couldn't find how to exclude stuff from the autodoc search, for example classes you don't want to appear. I suppose they must be declared private or something like that
  • - Some auto-generated pages are incomplete due to the GUI not being up. I tried adding FreeCADGui.showMainWindow() in conf.py, but doesn't work for FreeCADGui itself
  • - Some stuff I couldn't find how to "grab" with autotools. For example, you'd like to have all the methods of a FreeCAD Document. Couldn't find out how to get that...
Finally, since nothing depends on the source code itself (sphinx finds its doc by importing already built modules), there is no need to spread sphinx stuff inside the source tree... It could be in its own folder, and be used manually when one needs to generate the docs. I think I could upload the stuff I did until now in a subdir of the src/doc directory, so you guys can have a look... Ok? Or another better location?
wmayer
Founder
Posts: 20241
Joined: Thu Feb 19, 2009 10:32 am
Contact:

Re: wiki2qhelp.py failed to build a valid qhc & qch

Post by wmayer »

I think I could upload the stuff I did until now in a subdir of the src/doc directory, so you guys can have a look... Ok? Or another better location?
Yes, I think that's the perfect place to put the documentation.
User avatar
yorik
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: wiki2qhelp.py failed to build a valid qhc & qch

Post by yorik »

Okay, I added a shinx folder in src/Doc.
To build the doc, just do "make html" on linux. On windows you need to use the make.bat, but I didn't test. The result will be in _build/hml

One more thing I discovered:

- classes or functions that begin with underscore (_) are not read by sphinx. This is standard python way to mark private members (it's just indicative, python has no private stuff)

Things that are missing:

- Some docstrings could be better explained. We can make it a task for another release.
- When importing python modules, function definitions are complete with arguments. when importing C++ modules, not (compare the FreeCAD and the Draft modules, for example). I don't know what needs to be done
- I still couldn't find out how to import submodules, for example FreeCAD.Console or FreeCAD.Base.
- I also didn't discovered how to show FreeCAD.Document and FreeCAD.DocumentObject... They don't appear to be importable by sphinx
- Now we must discover where/how to upload that on Sourceforge...
User avatar
yorik
Founder
Posts: 13640
Joined: Tue Feb 17, 2009 9:16 pm
Location: Brussels
Contact:

Re: wiki2qhelp.py failed to build a valid qhc & qch

Post by yorik »

Online! http://free-cad.sourceforge.net/api/
I still need to find a way to put a link back to the wiki in it...
swosho
Posts: 17
Joined: Tue Sep 13, 2011 2:44 am

Re: wiki2qhelp.py failed to build a valid qhc & qch

Post by swosho »

Wow! Sometimes you guys move very fast! This is fantastic!
Post Reply