CMinx: A CMake Documentation Generator

Thumbnail Image
Date
2022-09-27
Authors
Butler, Branden
Richard, Ryan M.
Major Professor
Advisor
Committee Member
Journal Title
Journal ISSN
Volume Title
Publisher
Iowa State University Digital Repository, Ames IA (United States)
Abstract
This manuscript introduces CMinx, a program for generating application programming interface (API) documentation written in the CMake language, and CMake modules in particular. Since most of CMinx’s intended audience is comprised of C/C++ developers, CMinx is designed to operate similar to Doxygen (Heesch, 2022), the de facto C/C++ API documentation tool. Specifically, developers annotate their CMake source with “documentation” comments, which are traditional CMake block comments starting with an extra “[” character. The documentation comments, written in reST (reStructuredText, 2022), describe to the reader how the functions, parameters, and variables should be used. Running CMinx on the annotated source code generates reST files containing the API documentation. The reST files can then be converted into static websites with tools such as Sphinx (Sphinx, 2022) or easily converted to another format via Pandoc (Pandoc, 2022). Unlike other solutions for documenting CMake modules, CMinx knows the CMake language’s grammar. This enables CMinx to automatically extract function/macro signatures, even when functions are not documented. CMinx also integrates seamlessly into existing CMake build systems. CMinx’s output is highly customizable and easily controlled via a YAML (YAML, 2022) configuration file. CMinx has already proved to be an invaluable productivity tool in the authors’ other projects, and, given that other scientific software projects also rely heavily on source code written in CMake, we anticipate CMinx will prove invaluable to many additional projects as well. Concurrent with the submission of this manuscript, we have also released the first production version of CMinx, version 1.0.0. CMinx can be obtained from the Python Packaging Index via “pip install CMinx”. Alternatively, CMinx can be used as a CMake module via CMake’s “FetchContent” command. Despite only just releasing 1.0.0, the CMinx GitHub organization has already started to see attention and interest from developers not affiliated with the authors. We anticipate CMinx will be a useful productivity tool for the large swath of research software that uses CMake as their build system.
Series Number
Journal Issue
Is Version Of
Versions
Series
IS-J 10902
Academic or Administrative Unit
Type
article
Comments
This article is published as Butler, & Richard. (2022). CMinx: A CMake Documentation Generator. Journal of Open Source Software, 7(77), 4680. DOI: 10.21105/joss.04680. Copyright 2022 The Author(s). Attribution 4.0 International (CC BY 4.0). Posted with permission. DOE Contract Number(s): AC02-07CH11358.
Rights Statement
Copyright
Funding
Subject Categories
DOI
Supplemental Resources
Collections