Our official documentation tool dox has been updated and released on haxelib.
You can install or update dox using haxelib:
haxelib install doxPersonalize 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
Example - themeColor and title
haxelib run dox -i bin/xml -o bin/api-basic --title "API documentation" -D themeColor 0x1294f6
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
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.
