Yesterday, I read in the Cappuccino Gitter, that there is an issue with missing documentation for one of my favorite open source web technologies; cappuccino. Some files, specifically those with names starting with an underscore, aren’t processed by doxygen during the build, I figured I could probably figure out hoe doxygen selects and rejects files to process and minipulate that decision to include the files that were missing.

Turns out, that was easier than I could’ve hoped, the selection mechanism is configurable in a file that actually already had the setting I was looking for, and it was indeed set to a glob pattern that would exclude the files that were missing. There was also a setting that would exclude any symbols matching a similar pattern. So I forked the project on github and cloned it to my laptop changed the patterns so they’d exclude nothing. Removing exactly four characters from a configuration file, in two places. Changing




Now I had to figure out how the documentation was supposed to be built so I checked the JakeFile and found the task that builds the documentation is pretty darn cool:

    // try to find a doxygen executable in the PATH;
    var doxygen = executableExists("doxygen");

    // If the Doxygen application is installed on Mac OS X, use that
    if (!doxygen && executableExists("mdfind"))
            var p = OS.popen(["mdfind", "kMDItemContentType == '' && kMDItemCFBundleIdentifier == 'org.doxygen'"]);
            if (p.wait() === 0)
                var doxygenApps ="\n");
                if (doxygenApps[0])
                    doxygen = FILE.join(doxygenApps[0], "Contents/Resources/doxygen");

I love it! it checks to see if the `doxygen` tool is available and if it isn’t -and- it happens to be running on a Mac, it also uses spotlight to check if the DoxyGen desktop app is on the computer so it can use the shell tool it provides. I quickly installed the DoxyGen desktop app and figured I was all set. I had the source code, The documentation tool and I had made some changes that I believed would work.

Ofcourse I wasn’t quite so lucky, I managed to `jake docs` but was greeted with a friendly error explaining to me that `markdown` wasn’t available on my computer… and unfortunately, after searching for half an hour to no avail (I’ve had some fairly bad experiences using brew, so I didn’t want to go that route), I decided I’d roll my own. Thanks to Rider from JetBrains and the MarkdownSharp nuget package I had that working in under 15 minutes with jut a few lines of code and a shell script wrapper to integrate it with Jake. I was back on track!

Until I wasn’t… Now the output was filled with warnings that dot wasn’t available on my system. Thankfully, I quickly found a GraphViz installer package that worked really well for me. and I was finally off to the races.

The process kicked off, purred a bit and gave me a little over 120MB of files in a shiny new Documentation folder in my Cappuccino build directory. It looks fairly good to me, but I see some potential issues to discuss with the people behind Cappuccino before I can feel good enough to make.a pull request and hope to get a bit of my work integrated in possibly the coolest web application framework around. In the mean time, the result of my work is here for all the world to see.

Now if you’ll excuse me, I have to go and see if I can sync the documentations’ version number to the actual cappuccino version and figure out what I’ll need to be able to blog on the site.

Leave a Reply

Your email address will not be published.

April 2018