Polishing the pmp-library Documentation
High-quality and easily accessible documentation is a key feature of an easy-to-use software library. Since ease of use is a primary design goal of the pmp-library, I recently spent some time polishing up the pmp-library documentation.
We currently use Doxygen to build the full pmp-library.org website, including the user guide and reference documentation. As it stands today, Doxygen is the standard tool for C++ library documentation and comes with a whole bunch of powerful features such as:
- Auto-generated API documentation from annotated sources
- Support of Markdown pages for higher-level documentation
- Automatic cross-linking between pages and reference docs
- Proper citation and bibliography handling
That’s all well and good, but Doxygen also comes with a number of drawbacks. In my humble opinion, one of the most significant issues is the poor quality of the generated HTML output. First of all, the default output is rather cluttered, overly verbose, and not exactly clear and concise. There’s a plethora of index pages and menus so that it is not really straightforward to retrieve the information you are searching for. Furthermore, the HTML is not at all suitable for mobile devices. While this might not be too much of an issue for pure API reference docs, in our case this also means the the project homepage and user guide are not really accessible on a wide range of devices.
Being unsatisfied with the current state of affairs, I started to look around for alternative documentation generators. In particular, I investigated Jekyll, MkDocs and Sphinx plus Breathe. However, each of these alternatives comes with its own drawbacks, e.g., lack of auto-generated API docs and automatic cross-references in case of Jekyll and MkDocs, or a rather complicated toolchain in case of Sphinx.
Thus, I decided to see how far I can push a Doxygen-based solution by cleaning up and fine-tuning the HTML output. Checkout the latest version of the pmp-library website for results. I don’t think it is really worthwhile to go through all the modifications in detail. Instead, I’m just providing some pointers to the most important changes:
- Disable the overly verbose navigation tabs (
DISABLE_INDEX=YES) - Enable the flexible tree view navigation (
GENERATE_TREEVIEW=YES) - Use a custom page layout to change the structure of the output
- Include custom HTML headers and footers
- Customize the CSS to provide a more clean and minimalist appearance
- Change the overall color theme to match our logo
- Consistently use a few selected fonts
Finally, one particular annoying behavior on mobile devices is the messed up rendering of the split bar separating the tree view and the main content. I ended up modifying the the background image (splitbar.png) used for this component and copying it over using the HTML_EXTRA_FILES tag. Definitely not an elegant solution, but hey, it works for now.
So, even though I’m quite convinced that the customized HTML output represents a significant improvement compared to the standard one, there’s definitely lots of room for further improvement. In case you have any suggestions or spot any issues, please drop me a mail or directly submit an issue.