In the last days of January I attended the GNOME Developer Experience hackfest, remotely. This was a first for me since I have not attended a hackfest remotely before. It was also a first for the hackfest, that three remote participants signed up, and we had a discussion on desktop-devel-list as to how that should work.
My main project for the three days was to show people the documentation browser I’ve been working on. This got started a while after last year’s edition of the DX hackfest, which I didn’t attend, but the project was born out of a discussion with some people who were there and talked about it last year.
So, this was the problem I was hoping to solve. After a short-lived attempt to write my own web app using Semantic UI (a technology I’d still like to check out someday!) I figured, why bother when there was something that would fit the bill perfectly well: DevDocs, an open-source documentation browser that combines all kinds of documentation from elsewhere (mostly web development technologies) and presents them in a unified fashion with a useful but simple and elegant web app.
In the final quarter of 2015 I worked on this on and off, adding some code to the documentation generator
g-ir-doc-tool to make its output suitable for DevDocs to input, and some code to a forked version of DevDocs to import the GNOME documentation and make nice metadata and sidebar entries.
Here it is in action
At the hackfest I gave a demo (at 6:30 AM, because of the timezone difference!) to the other people there who were working on developer documentation. I got some good feedback from the people who were listening, discussed some of the shortcomings, and we discussed Mathieu Duponchelle’s new documentation tool, Hotdoc, as well. One good outcome was that the GNOME Developer Center now links to my instance of DevDocs (noting that it’s “experimental”.)
To talk about one of the limitations that we discussed at the hackfest: The approach I chose generates all the documentation from one file, the “GIR file,” which is the same approach that
g-ir-doc-tool has always taken. This is nice because it’s self-contained, but also incomplete: API references often include separate pages not connected to any API in particular, such as this one. I think using Hotdoc will help overcome this limitation, since Hotdoc is made for combining these sorts of things. I’m also happy not to work with
g-ir-doc-tool since all the stuff I added to it was basically bolted on the side, not really useful for anything else, and therefore not likely to be accepted upstream.
During the hackfest I also collaborated with Philip Withnall on some autoconf macros for GJS and GObject Introspection, which I’ll talk about in a following post…
Some of the other stuff that people worked on is summarized on Philip W.’s blog.