..
   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>`__.
