CMinx: A CMake Documentation Generator
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.