.. Copyright 2021 CMakePP

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

CMinx

.. image:: https://codecov.io/gh/CMakePP/CMinx/branch/master/graph/badge.svg?token=wbiPq8Gnrs :target: https://codecov.io/gh/CMakePP/CMinx

.. image:: https://joss.theoj.org/papers/10.21105/joss.04680/status.svg :target: https://doi.org/10.21105/joss.04680

Full documentation can be found here <https://cmakepp.github.io/CMinx/>__.

---

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:

.. code:: .py

pip install CMinx

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

.. code-block:: cmake

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 <https://cmakepp.github.io/CMinx/installation.html>__.

---

Example Usage

---

To use CMinx, first document your CMake modules like:

.. code:: cmake

#[[[

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:

.. code:: console

foo@bar:~$ cminx example.cmake

Which will generate:

.. code:: reStructuredText

####### 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 <https://cmakepp.github.io/CMinx/documenting/index.html>__ for more detailed usage instructions.

---

API Documentation

---

Full API documentation can be found here <https://cmakepp.github.io/CMinx/developer/api.html>__.

---

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 <https://github.com/CMakePP/.github/blob/main/CONTRIBUTING.md>__.