Dox 1.1 released, our documentation tool

Our official documentation tool dox has been updated and released on haxelib. The release contains theme related updates and easier customization.

Article by Mark Knol on 2016-08-12.

Comments

Our official documentation tool dox has been updated and released on haxelib.

You can install or update dox using haxelib:

haxelib install dox

Personalize documentation for your brand

We've seen many projects using dox to generate API documentation. This is great because documentation is part of a project success. That's why we continued improving the documentation tool.

Now some projects used the old themes, which we admit wasn't very pretty, other already start using the newer one since this is much greater. We've seen some developers copy/pasted the theme files and changed it to their needs. That works, but does not allow to update the theme with the latest features. With this release it is possible to only update the parts you actually need.

Default theme is more configurable

First of all, maybe you don't even need a custom theme anymore. The default theme has settings (theme colors, logo, website url, title, description) to customize it to your need. Go for a custom theme, if you need more expressive customization.

The following examples demonstrate what you can tweak using the default theme settings:

Example - no settings

haxelib run dox -i bin/xml -o bin/api-minimal

image

Example - themeColor and title

haxelib run dox -i bin/xml -o bin/api-basic --title "API documentation" -D themeColor 0x1294f6

image

Example - themeColor, textColor, title, website and logo

haxelib run dox -i bin/xml -o bin/api-advanced --title "Great API documentation" -D version "1.0.0 beta" -D website "http://haxe.org" -D logo "https://placehold.it/300x75/3c4db7" -D themeColor 0x1294F6 -D textColor 0x9BF1FB -D description "Just a perfect day to learn all about this framework!" -D source-path https://github.com/HaxeFoundation/haxe/blob/development/std/ -ex my.secret.pack

image

A demonstration of a real project with the default theme with custom settings is hxnodejs. It is automatically published online using Travis CI instructions on Github Pages.

But we want a custom theme

Yes, we wanted that too! The official haxe API documentation uses a custom theme too. But it "inherits" from the default theme. This allows to overwrite specific templates of a parent theme. Check out how the Haxe API documentation theme files are structured. In the config.json we tell its parentTheme is the default theme. From this point, we only changed the top bar, footer and package description for our specific needs.

Dox is documented

We've documented how you can work with dox in the dox wiki. This also contains a overview of all arguments/settings you can use with dox.

We encourage everyone to update to the latest documentation theme, it is easier to maintain and contains great improvements over the previous release.

As always, feel free to open a ticket on the GitHub for suggestions or bugs.

When you used the latest theme in your project, leave a link in the comments, we are looking forward to see it.

Avatar for Mark Knol

Mark Knol

Published 2016-08-12