Documentation Generator for the CMake Language
Project description
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.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.