Hello, Fedora recently added an XSLT to their dbus package to generate a devhelp index from the API documentation. Ubuntu adopted this XSLT to do the same. It seems worthwhile to ship this file upstream, so that distributions can easily build a devhelp index (after enabling XML code generation in Doxyfile.in, which is another patch, but trivial). Thanks for considering, Martin
Created attachment 12912 [details] XSLT for doxygen to devhelp Usage: xsltproc -o dbus.devhelp doxygen_to_devhelp.xsl doc/api/xml/index.xml
Created attachment 15572 [details] [review] add devhelp support and install/uninstall tested with "--enable-xml-doc --enable-doxygen" and "--disable-xml-doc --disable-doxygen", make install / make uninstall & make distcheck.
Adding this to my to-do list: Fedora, Ubuntu, Debian and Maemo all seem to patch this, one way or another.
Review of attachment 15572 [details] [review]: (This has bit-rotted a bit in the intervening 2 years, and the patch no longer applies cleanly.) ::: doc/Makefile.am @@ +33,3 @@ +install-doc: $(HTML_FILES) + @$(NORMAL_INSTALL) What does $(NORMAL_INSTALL) do? It looks like undocumented automake internals to me? @@ +58,3 @@ +# Build a DevHelp reference from the doxygen xml +$(devhelp_file): $(XML_INDEX) $(devhelp_stylesheet) + xsltproc --stringparam book_title "${PACKAGE_NAME} Reference Manual" \ configure.ac will need to check for xsltproc @@ +61,3 @@ + --stringparam book_name "${PACKAGE_NAME}" \ + --stringparam reference_prefix "../../../doc/${PACKAGE_NAME}/reference/html" \ + --stringparam docdir "../../../doc/${PACKAGE_NAME}" \ These parameters don't really make the XSLT fully generic: it still contains references to the tutorial, FAQ, spec, API reference. Nice idea, but I'm not going to commit this version right now; I'll stick with the Fedora one attached above (which we've been using for ages in Debian). @@ +64,3 @@ + -o $@ $(devhelp_stylesheet) $(XML_INDEX) + +$(HTML_INDEX) $(XML_INDEX): $(doxygen_configfile_source) $(beautify_docs_source) $(top_srcdir)/dbus/*.h What's beautify_docs_source? @@ +94,3 @@ + -rm -f $(HTML_FILES) $(devhelp_file) + -rm -rf api + -rm -f $(devhelp_file) Ignoring errors (the "-" prefix) is generally undesirable. ::: doc/doxygen_to_devhelp.xsl @@ +23,3 @@ + <sub name="API Reference" link="{$reference_prefix}/index.html"/> + </chapters> + </book> This is mis-nested: <functions> are also meant to be in the <book>.
Created attachment 42022 [details] [review] Generate XML from Doxygen This is a useful input format for XSLT, for instance to make a Devhelp index. Originally from Matthias Clasen in Fedora's dbus/1.0.1-2 package, via Ubuntu, Debian and Maemo.
Created attachment 42023 [details] [review] [2/8] Add doxygen_to_devhelp.xsl (from Fedora, via Debian) Originally committed by Matthias Clasen <mclasen@fedoraproject.org>.
Created attachment 42024 [details] [review] [3/8] configure.in: require autoconf 2.60 We already require it in practice, for AC_PROG_MKDIR_P. It also defines $(htmldir).
Created attachment 42025 [details] [review] [4/8] Check for xsltproc in configure.in
Created attachment 42026 [details] [review] [5/8] Use a stamp file to represent the Doxygen output This avoids thinking it's up to date if the Doxygen build fails, but writes partial output to index.html before failing.
Created attachment 42027 [details] [review] [6/8] docs: use $(MKDIR_P), which we already check for in configure.in mkdir -p isn't 100% portable, whereas $(MKDIR_P) can either be mkdir -p, install -d or (as a last resort) ./install-sh -d.
Created attachment 42028 [details] [review] [7/8] Install the Doxygen documentation to $(htmldir) Use ./configure --docdir=/foo (or --htmldir=/foo) to control where it ends up. For instance, Debian could use: --docdir=/usr/share/doc/dbus-1-doc --htmldir='${docdir}/html'
Created attachment 42029 [details] [review] [8/8] Build dbus.devhelp using doxygen_to_devhelp.xsl and install it
These patches look good. I like devhelp.
Patches applied, will be in 1.4.8 and 1.5.0. Thanks!
Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.