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
wiki2qhelp.py failed to build a valid qhc & qch
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
Be nice to others! Respect the FreeCAD code of conduct!
Re: wiki2qhelp.py failed to build a valid qhc & qch
Stop whining - start coding!
Re: wiki2qhelp.py failed to build a valid qhc & qch
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:
5) edit conf.py, add
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)
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:
Code: Select all
sys.path.append('/home/yorik/Apps/FreeCAD/lib/')
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)
Re: wiki2qhelp.py failed to build a valid qhc & qch
Great! Thank you!
Re: wiki2qhelp.py failed to build a valid qhc & qch
A little bit of CSS later...
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:
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...
Re: wiki2qhelp.py failed to build a valid qhc & qch
Yes, I think that's the perfect place to put the documentation.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?
Re: wiki2qhelp.py failed to build a valid qhc & qch
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...
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...
Re: wiki2qhelp.py failed to build a valid qhc & qch
Online! http://free-cad.sourceforge.net/api/
I still need to find a way to put a link back to the wiki in it...
I still need to find a way to put a link back to the wiki in it...
Re: wiki2qhelp.py failed to build a valid qhc & qch
Wow! Sometimes you guys move very fast! This is fantastic!