Following some pretty good feedback on Composure, the composition library for Haxe, I decided to get some code documentation published.
The result was a batch file which would generate documentation in Markdown format, which can then be manually committed and pushed to the github wiki. You can check out some examples of the results here, here & here.
The Documentation system
I wanted to have something generated directly from the code, and I had a preference for having it hosted within the Github Wiki system (for the simplicity of having code and docs accessible from the same place).
When a repository is created in Github, the system automatically creates a second repository to store the wiki files, which can be edited via the Github web interface or by cloning this wiki repository onto your local hard-drive and manually editing the files, which are in Markdown format, a simplified formatting language which gets converted to html by the github back-end.
I’d need to generate Markdown from my code and have it placed into wiki repository. I only found a few documentation systems which processed haxe code, and only one of them which allowed for custom templates, this was ChxDoc.
There were a few limitations to ChxDoc, specifically, that you have no control over what files get generated, or what file type it spits out. I’d have to reorganise and rename the ouput files as part of my batch file. ChxDoc works by processing an xml representation of the code, which is created by running the haxe compiler with the -xml flag, I’d include this step in my batch file as well.
I copied the default ChxDoc template and stripped all of the html tags out then added in the Markdown syntax. I didn’t need several of the output html files, so some of the template files remained untouched (deleting them caused ChxDoc to fail).
ChxDoc (and my template) supports the following tags:
@return (or @returns)
If you just want the template files, you can grab them here.
Setting up the Repositories
To streamline the documentation process, I added the wiki repository as a submodule to the main repository, this means that the wiki files would always sit in the same relative position to the main source code (i.e. in a ‘github-wiki’ folder).
In the ‘build’ directory, I created a batch file which does the following:
- Generates the XML representation of the code using the haxe compiler.
- Deletes the old documentation folder.
- Regenerates the documentation using the chxdoc program, my templates and the xml code graph.
- Deletes irrelevant generated files.
- Renames the ‘All Classes’ file (changing the file type from html to md).
- Changes the remaining html files to md files.
The batch file, template and ChxDoc are all included in the Composure repository (don’t tell me that binary files don’t belong in a repository you nazis) or you can just check out the batch file here (which will obviously only function on Windows).
I have updated the templates for the latest ChxDoc version (1.2.0).