Add a custom `macro` Sphinx directive

[robertodr]

Is your feature request related to a problem? Please describe. Not really a problem, but it might improve the generated documentation. The generated reST documentation for both functions and macros uses the .. function:: Sphinx directive. For macros, CMinx adds a note regarding the scoping rules.

Describe the solution you'd like CMinx could define its own directive for macros, to be used as .. macro::. When reading the reST files, this would make the difference between macros and functions slightly more immediate. The note about scoping rules should still be added: I'm guessing it's possible to include that bit in the definition of the custom directive.

Describe alternatives you've considered The current system works fine as well.

Additional context

This is related to the JOSS review process openjournals/joss-reviews#4680

[ryanmrichard]

@robertodr Thanks for the suggestion, but I'm inclined to punt on it unless you feel strongly about it. If we do punt on this suggestion, it's something that should be revisited if we ever write a Sphinx plugin for CMinx.

AFAIK the only way to create a custom directive is to make a Sphinx plugin. Admittedly writing a Sphinx plugin for a new directive is pretty simple (see here for an example). The bigger problem, IMHO, is that (again AFAIK) there's no way to add this directive without passing the complexity on to the user (assuming we need to write a plugin, then the user now has to install the plugin and register it in the conf.py file). The additional complexity is pretty minimal, but for many workflows the benefit from the complexity is also pretty minimal (I'm assuming that the new macro directive would basically be reST syntactic sugar around a function directive plus the disclaimer. I'm also assuming that in a typical workflow users don't actually look at the generated reST before running Sphinx, meaning they still get the same end result).

@AutonomicPerfectionist if we wanted to make it easier to possibly implement this down the road, how hard would it be to make the directives configurable via the configuration file? Something like:

rst:
  function_directive: "function"
  macro_directive: "function"

or (depending on whether Confuse allows it):

rst:
  directives:
    function: "function"
    macro: "macro"

(basically factor the directive out of the keys).

[AutonomicPerfectionist]

@ryanmrichard should be pretty simple to add such configuration, I'd have to look again but I'm pretty sure Confuse would allow the second option without much fuss

[robertodr]

OK, I understand that this is technically a bit involved, with very little gain. Feel free to disregard and close the issue.

[ryanmrichard]

I still think we should implement the configuration file option. We can close this issue after that.