Do you create project documentation in your company’s internal wiki? I did it for quite some time until I realized that a good old Doxygen combined with Git can do a much better job.
Doxygen is a well-known tool for generating documentation directly out of the annotated source code. However, it can be utilized to create technical documentation, too. In version 1.8.0, Markdown support was introduced to Doxygen. Markdown is a popular markup language. Plain text files written in Markdown format can be converted into HTML or many other formats. With Markdown support, creating technical documentation in Doxygen gets really easy.
Doxygen sample project
To get started, I read a very useful article describing how to enable support of plain Markdown files in Doxygen and a couple of gotchas one might encounter. Gotchas? No worries! In record time I was able to create sample technical documentation. As sample content I used a couple of articles from my blog which were also coded in Markdown. Now I’d like to share the project with you:
The project shows a basic document structure. If you want to learn more about Doxygen I recommend downloading the Doxygen source distribution
tarball or clone the Doxygen’s project
Git repository. After extracting the tar archive go to the doc directory where you can find the sources of the Doxygen’s
webpage. You can learn a lot by reading through them.
Doxygen provides good support for creating graphs and diagrams in your technical document. For instance, you can insert graphs in
DOT format with @dot or @dotfile tags. You can include
MSC sequence diagrams with @msc or @mscfile tags. To insert decent looking
PlantUML UML diagrams use @startuml tag. If you like to draw your diagrams in
Dia you can insert them to Doxygen via @diafile tag.
Conclusion
Doxygen is a very powerful documentation tool. Chances are that you’re already using it to generate a documentation from your source code. It makes a lot of sense to me to use Doxygen for project documentation instead of creating it in the Wiki. If you combine Doxygen with a good source control (e.g. Git) you gain the following benefits:
- History tracking and branching that no Wiki can provide
- The same development workflow for your documentation as well as for your source code
- Project documentation and source code at one place and possibly referencing each other