Option to show macro's value

[amykyta3]

Thanks for the great plugin! Not sure if this is already supported or not, but it could be useful in some situations to also show the macro's value in the rendered documentation.

Something like:

.. c:automacro:: MY_MACRO
    :file: example.h
    :show_value: True

I'm in a situation where I need to document a cross-language API, and there are several constants defined in macros that would be useful to propagate to the docs. For now, I'm working around by duplicating the macro value in the docstring comment.

[jnikula]

Thanks for the feedback! I understand the use case, and I'll look into it, but there are a few downsides:

• Basically all the directives translate to Sphinx C/C++ domain directives, and the c:macro directive doesn't have a way to provide the value. We'd have to somehow insert the value in the documentation.

• I'm not super keen on adding a lot of new options. It's a balance, and I'm aiming for sane defaults. For example, the cpp:enumerator (and the C domain equivalent, though it's undocumented) support documenting the value. Hawkmoth does this automatically based on whether the source code has = <value> for the enumerator or not. See https://jnikula.github.io/hawkmoth/stable/examples.html#enum

• If the macro values themselves contain macros, should they be recursively replaced? What about function-like macros? Could it be a sane default to document the value only if it's a "simple" number?

I'm not outright rejecting this, though, need to look into how it could be implemented. Using an enum might be a workaround in some cases.