Tag Archives: gtk-doc

gtk-doc knows your package version

tl;dr: gtk-doc will now bind autoconf PACKAGE_* variables for use in your documentation.

For various modules which use gtk-doc, it’s a bit of a rite of passage to copy some build machinery from somewhere to generate a version.xml file which contains your package version, so that you can include it in your generated documentation (“Documenting version X of package Y”).

This is a bit of a pain. It doesn’t have to happen any longer.

gtk-doc master (to become 1.25) now generates a xml/gtkdocentities.ent file containing a few PACKAGE_* variables as generated by autoconf. So, you can now get rid of your version.xml machinery, and change your top-level documentation XML file’s DOCTYPE to the following:

<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
 <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
 <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
 %gtkdocentities;
]>

You can now use &package_string;, &package_version;, &package_url;, etc. in your documentation. See gtk-doc.make for a full list.

Thanks to Stefan for getting this feature in!

The last GUADEC post?

GUADEC's over (and has been so for a while) and was great. The talk videos are up, and still I haven't blogged about the conference. Naughty me.

The conference was great: it was good to meet up with friends (old and new) again, get a bit of hacking done and hear lots of discussion about the future of GNOME. My thanks to the GNOME Foundation and my summer employer, Collabora, for sponsoring my accommodation and travel. Thank you to the local team for organising a brilliant GUADEC in a nice city, and here's to a successful GCDS 2011 in Berlin!

In other news, I've finally got fed up with forgetting to add new files in my project to either the project-wide header file or the documentation index, so I wrote some `make check` rules which will check for my braindeadness:

This one goes in the Makefile.am in the directory which builds your public header (such as gtk/gtk.h), and assumes a list of all the headers you're going to install is in public_headers, and that your main header's path is in main_header.

check-local: check-headers
check-headers:
	@any_missing=0; for header_file in $(public_headers); do \
		if test "x\(\)header_file>" $(main_header) >/dev/null; then \
				echo "$(main_header) doesn't appear to include \"\(\)any_missing"

This one goes in the Makefile.am in your gtk-doc directory (e.g. docs/reference), and only assumes the existence of DOC_MAIN_SGML_FILE, which needs to be defined for gtk-doc anyway.

check-local: check-xml-includes
check-xml-includes:
	@any_missing=0; find $(srcdir) -name "*.xml" | while read x; do \
		xml_file="\(\)xml_file" != "x$(DOC_MAIN_SGML_FILE)"; then \
			if ! grep "\"\(\)xml_file\""; \
				any_missing=1; \
			fi; \
		fi; \
	done; exit "$$any_missing"

I've filed bgo#627920 about adding the second rule to gtk-doc itself. I'm not sure the first rule is general enough to be put anywhere common.

Git commit hooks

I recently wrote/extended a couple of git commit hooks which have turned out to be rather useful. Once is a fairly standard commit-msg hook to check the format of the first line of a commit message is either "Release version x.y.z", "[tag] Message" or "Bug 123456 — Title":

tags="core|atom|gd|media|build|docs|tests|calendar|contacts|documents|picasaweb|youtube"
test "" != "$(grep -P '^(Release version [0-9]+.[0-9]+.[0-9]+|\[('$tags')$$ [\S].+[\S]|Bug [0-9]+ — [\S].+[\S])$' "$1")" || {
 echo -e >&2 "First line of commit message should be in one of the following formats:\n * 'Bug 123456 — Title'\n * '[tag] Message'\
 \n * 'Release version x.y.z'\nValid tags are:\n * ${tags//|/\n * }"
 exit 1
}

Just define the tags your project allows in the tags variable, separated only by pipes.

The other hook is a pre-commit hook to ensure any new API has a Since: tag if it's got a gtk-doc comment. It's implemented as a modification of the sample pre-commit hook, so here's the diff:

--- /home/philip/Downloads/4m8QcjYs.txt    2010-03-28 19:14:50.432440248 +0100
+++ pre-commit    2010-03-22 20:37:47.612794352 +0000
 my $filename;
 my $reported_filename = "";
 my $lineno;
+    my $in_gtk_doc_comment = 0;
+    my $used_since_tag = 0;
 sub bad_line {
 my ($why, $line) = @_;
 if (!$found_bad) {
@@ -64,6 +68,19 @@
 if (/^([<>])\1{6} |^={7}$/) {
 bad_line("unresolved merge conflict", $_);
 }
+        if (/^\s*\/\*\*$/) {
+        $in_gtk_doc_comment = 1;
+        $used_since_tag = 0;
+        }
+        if ($in_gtk_doc_comment && /^\s*\*\*\/$/) {
+        $in_gtk_doc_comment = 0;
+        if (!$used_since_tag) {
+            bad_line("new gtk-doc commented API without a Since: tag", $_);
+        }
+        }
+        if ($in_gtk_doc_comment && /\*\s+Since:\s+[0-9]+.[0-9]+.[0-9]+$/) {
+        $used_since_tag = 1;
+        }
 }
 }
 exit($found_bad);

It looks for the start of a gtk-doc comment block in any added code, and errors if it doesn't find a Since: tag before the end.

Hopefully these'll be useful to somebody. They've both turned out to be more useful to me than I'd hoped, so hopefully my commit messages make a little more sense now. The code for both of them is in the public domain.

Totem API documentation

Totem now has API documentation for the API it exposes to plugins. The documentation has actually been in the source code a while, but we couldn't build pretty reference pages from it. Last night, I separated most of Totem out into a noinst library, which we now use with gtk-doc to build pretty documentation. When we make the next tarball release, the documentation should make its way to library.gnome.org for all budding plugin authors to read.

I was all set to copy-and-paste the required gtk-doc sorcery from another module and leave it at that, when I came across this gtk-doc GNOME Goal. It turns out none of the modules from which I would copy the black magic were making full use of recent gtk-doc features, such as namespace support. Another little bit of hacking later, and Totem now has a symbol index which is actually sorted usefully, and will check the documentation when running `make check`.

On top of that, Stefan Kost has recently added syntax highlighting support for code examples to gtk-doc trunk. Good work!

Auto-generated class hierarchy diagrams

Unfortunately still working on that coursework, I've just added support in the API documentation makefile to automatically generate a class hierarchy diagram using the GObject hierarchy file created by gtk-doc and marshalling it to GraphViz. It basically analyses the depth of each line in the hierarchy file and creates relationships in the dot file as appropriate. It doesn't sound complex, but it took a heck of a lot of fiddling to get automake happy with my syntax.

graph-build.stamp:
	echo "digraph class_hierarchy" > $(DOC_MODULE).dot
	echo "{" >> $(DOC_MODULE).dot
	(IFS=$$'\n'; \
	for current_line in `cat $(DOC_MODULE).hierarchy`; do \
		depth_colours=( red green blue yellow ); \
		depth=`echo $$current_line | grep -o "  " | wc -l | sed s/\ //g`; \
		echo "$$current_line [shape=box, color=$${depth_colours[$$depth]}]" >> $(DOC_MODULE).dot; \
		last_line[$$depth]=$$current_line; \
		if [ $$depth -gt 0 ]; then \
			echo "$${last_line[`expr $$depth - 1`]} -> $$current_line" >> $(DOC_MODULE).dot; \
		fi; \
	done)
	echo "}" >> $(DOC_MODULE).dot
	dot -Tpng $(DOC_MODULE).dot > $(DOC_MODULE).png
	touch graph-build.stamp

Building PDFs of documentation

Still working on that coursework project, I'm now building PDFs of the three pieces of documentation the application itself requires: the API reference, the source code listings and the user manual.

Using gtk-doc to build the API reference makes it quite easy to add something in the Makefile to build a PDF from the DocBook:

docs/reference/Makefile.am

I've put this at the bottom of the Makefile.am, and it's all working nicely, apart from the fact that distcheck (legitimately) complains about me redefining all-local. I can't find any other way to make it build the PDF while also building the normal docs with make docs, so my question here is: how do I make this implementation cleaner?

If anybody wants to use it, they'll need to install dblatex.

The next piece of documentation is the source code listing. This is completely custom, using source-highlight to make LaTeX files for each source file, and then pdflatex to build them into a PDF.

docs/source/Makefile.am

I'm quite pleased with the way this works, although I'm sure there will be better solutions out there. source-highlight deposits many LaTeX files in the build directory, which are then included in the PDF build by dint of being automatically concatenated together and included by a surrounding LaTeX file, project-name-source.tex.

docs/source/two-hundred-club-source.tex

Finally, the user manual also needs building into a PDF. This again uses dblatex, although it's a little more complex, as a PDF has to be built for each language directory in the help directory.

docs/help/Makefile.am

Hopefully some of that will be helpful to somebody in a similar situation, and I'd welcome any hints or pointers as to how to improve the implementations, as my automake powers are about as strong as a damp tissue.

Revamp, GTK+ apps on Windows and more documentation

I've just finished converting the site to use WordPress instead of the custom software I'd previously been using. It'd been getting too time-consuming to keep everything maintained and up-to-date with the latest things going on on the Internet, and I'd been reduced to making posts via phpMyAdmin due to various things breaking. Hopefully, this should be better, and a lot less hassle to keep running. I apologise if the transition has messed up the feed for anyone, but I've tried my hardest to redirect all the old URLs, so things should keep working as before.

Recently, I had to compile my computing coursework for Windows, as the person for whom it's written only uses Windows. Much to my delight, once I'd figured out the terminology and basic principles, getting it to cross-compile for Windows using MinGW was quite easy! Since I couldn't find much documentation on the process while doing it, I've written up the steps I took, and perhaps someone else will find them useful.

Last month, I also managed to write up some API documentation for totem-pl-parser, which has been on the to-do list for a little while. It was quite easy to get the hang of gtk-doc, too, and once I'd got started, the documentation got done quite quickly. If anyone's implementing anything using totem-pl-parser, I'd appreciate any feedback on the usefulness of the documentation, as it can always be improved.