README.rst

CMinx

Full documentation can be found here.

Statement of Need

CMake build systems can be extended by writing CMake modules. CMake modules typically consist of one or more functions (or macros) written in the CMake language. In an effort to treat infrastructure as code, we need to be able to generate API documentation for these CMake modules. CMinx addresses this need by generating reStructuredText files from documented CMake modules. Since CMinx understands the grammar of the CMake language, these comments only need to focus on describing the code and not duplicating it.

Installation Instructions

The easiest way to install CMinx is via pip. Simply run:

pip install CMinx

CMinx can also easily be used as part of a CMake workflow by adding:

include(FetchContent)
FetchContent_Declare(
    cminx
    GIT_REPOSITORY https://github.com/cmakepp/cminx.git
)
FetchContent_MakeAvailable(cminx)
cminx_gen_rst("${input_dir}" "${output_dir}")

to your CMakeLists.txt file. More detailed instructions, can be found here.

Example Usage

To use CMinx, first document your CMake modules like:

#[[[
# A brief description.
#
# A more detailed description, must be separated from the brief by at least
# one blank line.
#
# :param param0: The 0-th parameter passed to the function
#]]
function(example param0)
    message("This function says: ${param0}")
endfunction()

The documentation resides in a normal CMake block comment aside from the fact that the block comment starts with an extra [ character. The body of the block comment is extracted into the reStructuredText file more or less verbatim so reStructuredText markup can be used within the comment for more formatting options. Assuming the above CMake module lives in example.cmake, the API documentation is generated by running:

foo@bar:~$ cminx example.cmake

Which will generate:

#######
example
#######

.. module:: example


.. function:: example(param0)

   A brief description.

   A more detailed description, must be separated from the brief by at least
   one blank line.

   :param param0: The 0-th parameter passed to the function

See here for more detailed usage instructions.

API Documentation

Full API documentation can be found here.

Contributing

In short, we try to be a welcoming community. If you have questions, suggestions, bug reports, etc. open an issue and we will address them as soon as possible. If you want to contribute code, that's even better. We recommend you start a draft PR early in the process so we know the contribution is coming and can help you along the way.

CMinx is part of the CMakePP organization, whose contributing guidelines can be found here.