Re: Using ddox with GtkD for documentation

Gerald Nunn

Posted Sun, 27 Dec 2015 17:29:11 GMT in reply to Mike Wey

On Fri, 25 Dec 2015 11:29:03 +0100, Mike Wey wrote:

ddox also hangs when you are using serve-html and try to access
gdk.Window.Window.

One problem seems to be the “ and ” characters in the comments, but
there are more issues it hangs on.

The problem appears to be unicode in general, ddox does a lot of character parsing of the comments in order to create links between various entities and I suspect that the multi-byte unicode characters in UTF-8 are screwing it up. I updated the script to convert unicode double and single quotes to their ASCII equivalents and then run the rest through iconv for everything else to generate an ASCII docs.json. This then works fine with ddox and it can successfully generate documentation for all classes. A quick look through the generated docs look fine to me from a readability point of view, I don't see any obvious problems but I suspect Mike you'd be in a better position to know where the problem areas are likely to be.

The updated script is below. Mike I'd be willing to put some additional effort into modifying the ddox diet templates that generate the pages to try to optimize them for GtkD but is using ddox something the project would be willing to consider? I don't want to invest a bunch of effort in this if it's a non-starter for GtkD.

#!/bin/sh

mkdir -p ddox/temp

echo "Generating JSON file for modules"

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
echo "Adding comment to modules"
sed -i 's/"kind" : "module",/"kind" : "module", "comment" : " ",/g' ddox/docs.json

#Fix problem with unicode quotes by replacing them with ASCII quotes
echo Replacing unicode double and single quotes with ASCII equivalent
sed -i 's/“/\&quot;/g' ddox/docs.json
sed -i 's/”/\&quot;/g' ddox/docs.json
sed -i 's/’/\&#39;/g' ddox/docs.json

echo "Convert UTF-8 to ASCII for everything else"
mv ddox/docs.json ddox/docs_utf8.json
iconv -f utf8 -t ascii -c ddox/docs_utf8.json > ddox/docs.json

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

# Use dub to run ddox and generate offline ddox documentation
dub run ddox -- generate-html --navigation-type=moduleTree ddox/docs.json ddox