GNOME Bugzilla – Bug 122450
stylesheet to generate devhelp documentation from doxygen xml
Last modified: 2004-12-22 21:47:04 UTC
Here is a stylesheet that will convert the xml output of doxygen to a devhelp file. A number of changes need to be done to the build process for a resulting file to be generated; those changes should be done by someone who is intimitaly familiar with the the gtmm build system. Changes are described below. - line 128 of docs/reference/Doxyfile.in should be changed from GENERATE_XML = NO to GENERATE_XML = YES - docs/reference/Makefile.am has to be changed to call an xslt processor after doxygen has ran. Probably add a line on line 22, that should look something like this: xsltproc -o html/gtkmm-$(VERSION).devhelp ../../tools/doxygen2devhelp.xsl xml/index.xml I don't know the exact name of the version macro, so the above is obviously only a suggestion. A possibility would be to allow the user to specify which xslt processor to use. This is difficult since other processors (eg Saxon) have a different way of specifying parameters. There should also be a check (probably earlier on in the build process) to see if there is an xslt processor available. - There are different ways to make this documentation known to devhelp; they are described in the README that comes with devhelp (at least with version 0.7). I'm not familiar enough with Gnome to comment on which variables vary the least across Gnome installations; probably a symlink from should be made from /usr/share/gtk-doc/html to the actual place the gtkmm documentation is installed to.
Created attachment 19984 [details] Stylesheet to generate devhelp file
Ok, I've added a small patch which will do 1 & 2 of the initial comment. Patch made against CVS of gtkmm2 of 16th sept 2003. The stylesheet that is also attached to this bug report still needs to be added; put it in the tools/ subdirectory. Point three of the initial comment still has to be done, I couldn't figure out how to do that. One note is that it would be nice if the filename for the generated would have the version number in it, but I didn't know of a way to do it. If that information is available in the Make phase, the -o line of the xsltproc command has to be changed to reflect that.
Created attachment 19990 [details] [review] patch to Doxyfile.in and Makefile.am
It just seems to create a file with these contents: <?xml version="1.0"?> <book xmlns:fo="http://www.w3.org/1999/XSL/Format" title="Gtkmm Library Reference Manual" name="gtkmm" link="index.html"> <chapters> <sub name="Classes" link="reference/html/classes.html"/> <sub name="Namespaces" link="reference/html/namespaces.html"/> </chapters> <functions/> </book> That does not seem very useful. I guess that devhelp can not index the symbols. Well, it's better than nothing, I suppose.
Hmm, the .xsl does seem to do a lot more. Maybe it's because I have put the .xsl file in docs/reference instead of tools/. I'll commit what I have to cvs when I get a chance (probably a couple of days) and we can figure it out.
That is checked in now. Please take a look. And please see "How do I create a patch" here: http://www.gtkmm.org/bugs.shtml Thanks.
Do you have any idea?
Sorry, I haven't had time just yet. I won't until next weekend. I'll follow it up ASAP.
ping?
Pong. I took the latest version and it looks ok (well, it looks like what I send in, at least). I did have to do 'make devhelp-reference'; it looks like it's not build by default, but that's probably on purpose. Was there anything else you'd like me to do now?
I get a very small .devhelp file. Could you send me (by email) a copy of your generated .devhelp file so I can see what should be generated, please.
ping.
Pong again. It's rather hard for me to do anything in a timely way because I'm only near a linux machine a few hours a week, and even then I have other things to do besides this. I will attach a file that will show you what it should look like. It was generated from the file that I attached initially. If the only thing that is generated is an empty devhelp file, the most probable cause is that the index.xml is not found. Maybe the doxygen config is not right, or a path somewhere, or the makefile rules don't get updated correctly. All I can say from here is that It Worked For Me last week, that was with an updated cvs. When I have an opportunity I'll do a fresh checkout and try if that works for me; but as I said I cannot guarantee punctuality.
Created attachment 20976 [details] Sample output, rudimentary devhelp docs of gtkmm
I don't know about the output in your's index.xml, but mine had doxygenindex as the "top-level" field instead of doxygen. Thus failing the doxygen/compund/$kind='whatever' extraction. Changing the entries with doxygen to doxygenindex in the doxygen2devhelp.xsl file fixed my problem with the very short output. Thus changing: <xsl:apply-templates select="doxygen/compound[@kind='namespace']"> to: <xsl:apply-templates select="doxygenindex/compound[@kind='namespace']"> enabled the parser to extract the namespace information out of the index.xml file. Hope this helps for you to. BTW: My doxygen version is 1.3.4 (Debian SID).
This could very well be the problem that Murray is seeing. I have written the stylesheet for the output of Doxygen 1.3rc3.
That's it. Thanks.
I see the Classes and Namespaces pages in devhelp, and the links work. Should I be able to search for gtkmm methods? That doesn't seem to work.
ping (ping has worked before)
Pong. Ping worked before but I missed the last notification email about the last question. Send me the stylesheet that is generated and I'll have a look. Searching for methods names should work, maybe another element name was changed in recent doxygen incarnations.
OK. I sent that in an email (it's too big for a bugzilla attachment), but it would be really nice if you started working from cvs yourself.
ping
Hmm I don't see why it doesn't work for you. For example, Gtk::AccelMap has a member function 'change_entry'. So when I type 'change_entry' into the search box, I see two results: change_entry and gtk_accel_map_change_entry, and when I click on change_entry, I get the right page (the Gtk::AccelMap page). The function search is in the <functions> element of the devhelp page, could you check if that is generated in your file, it is in mine.
I can't check rýght now, but I sent the devhelp file to you, as requested. And can't you just build the cvs version?
Ok, I've build the cvs version, and it works as I described above; so function searching in the cvs version works for me.
Hmm, yes, it seems to be working now, though I had to correct the devhelp file name and location (done in cvs). I notice that the anchor links don't work (it doesn't go straight to the method instead of the top of the page), but that's probably a gtkhtml problem. Thank you. I have done this for libglademm already and will do it for the others, so check the changes if you have thoughts. Thanks again.