I’ve built a small plug-in exploring a imho fundamental topic for a platform, that is the documentation.
screenshot
It works mostly like javadoc but it uses xhtml (via flyingsaucer).
The plug-in takes a zipped tree of xhtml pages, folders and resources and generates the index tree.
Each folder is a group of topics and the pages in that folder are considered elements of that topic, so creating the documentation it’s a matter of creating a tree of documents in the file system and zipping them. The zip can be local or remote.
I have not tested it yet but being the browser being a netbeans app, it could interact with the ide itself (like a link that pops up the “new project” folder for an hypothetical “create project” tutorial or a link that loads a remote nebeans project, things like that).
So, it could be just a matter of having the time to create the documentation.
The NetBeans help system is thats built in is quite sophisticated, you also got explanations and stuff for single properties etc. Then theres also the omni-present F1 help context where you can link almost any place where the user presses F1 to a help entry.
Thing is, the documentation of jme3 is not completely ready or stable yet and starting to enter it into multiple systems (wiki, help etc.) and updating it there will probably be a bit too much right now. As soon as wiki and javadoc get into a stable state however I intend to pull over the information. I also thought about a plugin pulling the latest info from the web. If you want to start and maintain this already of course you're very welcome 
We could perhaps link the names of wiki pages into the application based on the packages or source folders being used…
I think we need to better define documentation in the case of what we want in the platform… What level of verbosity would be appropriate for inside of the application vs. what is fine just living on the website?
I was thinking about a documentation for the editor, not about the libraries. Something like "what can i do with the gde platform". A kind of wiki, but integrated into the editor itself. I discarded the integrated java-help system of Netbeans because it requires the documentation writer to produce (and update) deployment descriptor files.
pgi said:
I discarded the integrated java-help system of Netbeans because it requires the documentation writer to produce (and update) deployment descriptor files.
Well I dont think thats a problem, the svn is accessible and Ruth knows her way around NetBeans pretty well ;) For now I collect documentation for jMP here.
I thought about this, what about a "Tutorial Plugin" that uses zathras' tutorials (code and text in wiki) to guide a newbie into the depths of jme3…?
Looked into the JavaHelp documentation system again and I will definitely use it as its built-in and the rest of the IDE docs are also available via it. I dont exactly know what you mean by "deployment descriptor files", in the end its also just a bunch of html files and some xml TOC/index lists. They could even be updated by the build script from some web page or something. I'll start to mirror the wiki docs by hand into the javahelp files sometime soon so we have at least some docs already there.
Sorry for the delayed answer, i missed the reply.
For deployment descriptors i mean the indexing files. Of course if you can automate the generation of the indices then the problem goes away.
Packing the tutorials was exactly what i had in mind and what I wanted to avoid was the need to duplicate the source base.
In the end what is important is to grant access to the documentation as close as possible to the platform, if you can do that with the netbeans help system its fine.
pgi said:
In the end what is important is to grant access to the documentation as close as possible to the platform, if you can do that with the netbeans help system its fine.
I think so, it should be possible to link any component to a help entry thats opened by pressing F1, I think thats fine and as said also more consistent. In fact one can directly link online sources as well, so I think most stuff can be covered by that.
I added basic documentation with online-links to the wiki to the jMP help system now, also included a page with links to the tutorial series. It works quite well with the dokuwiki html-output option, lust the links on the pages are not html-ified :|… So I guess I will have to add a similar option to our new wiki
If you want to check it out, update jMP and press F1. If SceneExplorer, SceneViewer or SceneComposer are the frontmost window the corresponding help entry should appear automatically, though this is not yet working properly when the "wrong" widget is selected.
Cheers,
Normen
Tested it (Ubuntu), works like a charm, good job.