CMinx: A CMake Documentation Generator

Butler, Branden; Richard, Ryan M.

CMinx: A CMake Documentation Generator

File

IS-J 10902.pdf (208.54 KB)

Date

2022-09-27

Authors

Butler, Branden

Richard, Ryan M.

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

IS-J 10902

Academic or Administrative Unit

Ames National Laboratory

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.