Using ddox with GtkD for documentation

Gerald Nunn

Posted Thu, 24 Dec 2015 20:01:55 GMT

Like some other GtkD users, I find using the documentation a bit frustrating so I thought I would take a stab at an alternative, namely ddox. If you are unfamiliar with ddox, it's used to provide the documentation for Vibe and Phobos and a link to the project can be found here https://github.com/rejectedsoftware/ddox. The one nice thing with ddox is that it provides a searchable interface so you can just type into a text box and it will show the entries that match rather then scroll up and down a long list like we do currently with candydocs. With a project like GtkD which has a plethora of classes I find this a big time saver.

This post is about getting ddox working with GtkD, note that while what I am posting here works it's not perfect, I'm posting in the hopes of getting some discussion going and maybe get to a point where we can improve the official GtkD documentation. On that note, here's my instructions.

Using ddox consists of two script files, the first script file generates the docs.json file required by ddox while the other starts the ddox server which serves the documentation. The script that generates the documentation is called makeddox.sh and goes in the root Gtkd directory, it's a peer to the existing makedocs.sh. The script creates a ddox directory (similar to the existing docs directory), the contents of the script file are as follows:

#!/bin/sh

mkdir -p ddox/temp

echo "MODULES =" > modules.ddoc ;grep -h -e "^module" src/* -r | sort -u | sed 's/;//' | sed 's/\r//' |  sed 's/module \(.*\)$/\t$(MODULE \1)/' >> modules.ddoc
grep -h -e "^module" srcgl/* -r | sort -u | sed 's/;//' | sed 's/\r//' |  sed 's/module \(.*\)$/\t$(MODULE \1)/' >> modules.ddoc
grep -h -e "^module" srcsv/* -r | sort -u | sed 's/;//' | sed 's/\r//' |  sed 's/module \(.*\)$/\t$(MODULE \1)/' >> modules.ddoc
grep -h -e "^module" srcvte/* -r | sort -u | sed 's/;//' | sed 's/\r//' |  sed 's/module \(.*\)$/\t$(MODULE \1)/' >> modules.ddoc

dmd -o- -D -X -Xfddox/docs.json -Ddddox/temp modules.ddoc docs/candy.ddoc \
	src/gtk/*  src/gtkc/* src/glib/* src/gio/* src/gdk/* \
	src/gobject/* src/gthread/* src/atk/* \
	src/pango/* src/cairo/* src/gdkpixbuf/* \
	srcgl/glgdk/*  srcgl/glgtk/*  srcgl/gtkglc/* \
	srcsv/gsv/*  srcsv/gsvc/* \
	srcvte/vtec/* srcvte/vte/* -op

# Delete all html files generated by D ddocs
rm -rf ddox/temp/*

# insert a fake comment for all modules so that ddox doesn't filter out the modules since 
# none of them have comments
echo Adding comment to modules
sed -i 's/"kind" : "module",/"kind" : "module", "comment" : " ",/g' ddox/docs.json

# Filter out everything except public members that are documented
dub run ddox -- filter ddox/docs.json --only-documented --min-protection Public

# Use dub to run ddox and generate offline ddox documentation
# This doesn't work, hangs on gdk.Windows
#dub run ddox -- generate-html docs.json ddox

This will create a ddox/docs.json file, now we are ready to run the ddox server. Before executing the next step, you need to copy the /public directory from ddox into the GtkD/ddox directory so that the ddox web server can access the css and js files it needs to serve the documentation. Once you've done that, use the following command to start the ddox server from the root GtkD directory:

dub run ddox -- serve-html ddox/docs.json --navigation-type=ModuleTree --web-file-dir=ddox/public

If everything went to plan you should see a nicely stylized site with the GtkD documentation. If you what you see instead is plan HTML with no styling you made a mistake in copying the ddox public web files, you can view source on a page and see where ddox is looking for the files.

Some issues and potential improvements as follows:

The ddox generation of off-line documentation hangs on gdk.Window so running the ddox server is required, need to look into this more
AFAIK GtkD candydocs only generates docs for things which have documentation comments, for example if you look at the source code for vte.Terminal there are lots of un-documented public members which don't show up in candydoc. ddox has a switch to do the same thing, only-documented, but since none of the modules are documented they get stripped out leaving you with an empty docs.json file. If the project wanted to switch to ddox at some point in the future it would be nice if the auto-generation could include a blank doc comment for modules similar to what it does for classes. Right now I'm handling this in the script with sed to insert a blank comment
GtkD has a style of a 1:1 match between module and class, this is a bit annoying with respect to browsing the ddox documentation since you have to click on the module first and then the class. For the search facility in ddox it's not an issue since you can directly click on the class but it would be nice to have a pass-through when there is only one documented item in the module.
I'm not a fan of the default ddox style of showing the class with only summary info and forcing the user to click on the member to see it's full definition. Need to spend some time figuring out if there is way to generate a single page for each class with all of the info.

Anyway, that's it for now, like I said I'm hoping this will kick off some discussion about GtkD documentation and we can get a bit of critical mass to improve the situation.