Documenting a Macro

From the perspective of a CMinx user, one documents a macro in the same manner as a function. For example:

#[[[
# This macro says hi.
# This documentation uses a differing format,
# but is still processed correctly.
#
# :param person: The person we want to greet.
# :type person: string
#]]
macro(macro_say_hi person)
   message("Hi ${person}")
endmacro()

Since macros and functions behave differently in CMake (the biggest difference being that functions introduce a new scope, whereas macros do not). CMinx will automatically note in the generated documentation whether the command being documented is a function or a macro.

########################
test_samples.basic_macro
########################

.. module:: test_samples.basic_macro


.. function:: macro_say_hi(person)


   .. note:: This is a macro, and so does not introduce a new scope.

   This macro says hi.
   This documentation uses a differing format,
   but is still processed correctly.
   
   :param person: The person we want to greet.
   :type person: string
   

CMinx supports the same documentation features for macros as it does for functions. This includes determining when a macro has keyword arguments as in the following example.

#[[[
# Variation of macro_say_hi, which takes lists of people and cats to say hi to.
#
# This macro is basically the same as ``macro_say_hi``, but accounts for the
# fact that you may want to say hi to multiple people and maybe even a cat or
# two.
#
# :param me: The name of the person saying hi.
# :type me: string
#
# **Keyword Arguments**
#
# :keyword PERSONS: The person or persons to say hi to.
# :type PERSONS: list of strings
# :keyword CATS: The cat or cats to say hi to.
# :type CATS: list of strings
#]]
macro(advanced_macro_say_hi me)
    cmake_parse_arguments(PARSE_ARGV 1 _asht "" "" "PERSONS;CATS")
    message("I, ${me}, want to say hi to the following ")
    message("people: ${_asht_PERSONS} and the following cats: ${_asht_CATS}")
endmacro()

CMinx will automatically add **kwargs to the macro signature line in the output RST.

###########################
test_samples.advanced_macro
###########################

.. module:: test_samples.advanced_macro


.. function:: advanced_macro_say_hi(me **kwargs)


   .. note:: This is a macro, and so does not introduce a new scope.

   Variation of macro_say_hi, which takes lists of people and cats to say hi to.
   
   This macro is basically the same as ``macro_say_hi``, but accounts for the
   fact that you may want to say hi to multiple people and maybe even a cat or
   two.
   
   :param me: The name of the person saying hi.
   :type me: string
   
   **Keyword Arguments**
   
   :keyword PERSONS: The person or persons to say hi to.
   :type PERSONS: list of strings
   :keyword CATS: The cat or cats to say hi to.
   :type CATS: list of strings