search

vovkos / doxyrest

A compiler from Doxygen XML to reStructuredText -- hence, the name. It parses XML databases generated by Doxygen and produces reStructuredText for the Python documentation generator Sphinx.
MIT License
306 stars 23 forks source link

feature request: convert doxygen \note commands to rst ..admonition:: blocks #44

Closed LexouDuck closed 3 years ago

LexouDuck commented 3 years ago

Hey - first of all I must thank you for creating this tool ! It has been of great use to me.

Like the title states, I would for like to have \note/@note commands to be converted into .. admonition:: blocks in the .rst output.

For now, I have been able to work around this somewhat, using custom commands in the doxygen config file - basically, something like this:

ALIASES = \
admonition{1}="\
^^@if DOXYREST\
^^  @verbatim\
^^.. admonition::\
^^          \1\
^^  @endverbatim\
^^@else\
^^  @note \1\
^^@endif\
^^"

(and i do ENABLED_SECTIONS = DOXYREST in the commandline, only when generating XML output) Notice the @verbatim/@endverbatim blocks inside said commands. The problem with this approach is that I must then use a custom script to fix the .rst files, as they will have incorrect indentation.

As you know, whitespace, and indentation in particular, is very important in reStructuredText. As far as I know, doxygen trims any and all leading whitespace/asterisk/forward-slash characters. But things are different when using a custom command: inside a user-defined alias, whitespace is preserved, except for newlines (you have to write newlines manually by typing ^^). this is causing all kinds of inconsistent behavior - so yeah, my workaround is far from perfect, which is why I am requesting this feature.

vovkos commented 3 years ago

Thank you for the report, and apologies for the delay.

Doxyrest 2.1.3 supports automatic conversion of the \note, \attention, \warning Doxygen commands to the .. note::, .. attention::, .. warning:: reStructuredText directives.

Also, I would suggest a different workaround (applicable to situations when some reStructuredText constructs are required but not yet natively supported by Doxyrest). Structure the original Doxygen comment as follows:

/**
\verbatim

.. note:: Note Title Goes Here

    Note contents goes here.

\endverbatim
*/

Inside of the verbatim block you are free to use any reStructuredText you want; it will be passed-through directly to Sphinx.

But once again, the original issue doesn't require this as the \note command is supported natively now.