The Doxyfile validator is too strict with the ALIASES variable

[santiagopagani]

The Doxyfile validator is currently checking that the ALIASES variable is set to ["rst=\\verbatim embed:rst:leading-asterisk", "endrst=\\endverbatim"]. This is however too strict and there are multiple cases where this check does blocks doxysphinx from moving forward.

Use case 1: Other ALIASES are also defined
In our project we have other macros also defined.
With the current validator all other ALIASES (aside from rst and endrst) need to be removed for doxysphinx to move forward.

Use case 2: Adding a newline to the rst or endrst alias
In order to reduce lines of code, we have added a newline to the alias definitions.
Namely, we have defined rst=^^ \\verbatim embed:rst:leading-asterisk and endrst=\\endverbatim ^^.
In this way, we do not need an empty newline after the rst macro and before the endrst macro.
With the current validator an error is thrown, although the macro is properly aligned with doxysphinx requirements and it works fine.

Use case 3: Using \internal inside the rst or endrst alias
In our project, aside from doxysphinx, we are also using Breathe to directly embed Doxygen documentations in some rst files.
Nonetheless, it can be that we are embedding a class or method that has an rst block inside of it defining a need object.
In this case, Sphinx complains that there is a duplicated ID for a need.
A simple workaround for this is to add the \internal command in our aliases.
Namely, we have defined rst=\internal ^^ \\verbatim embed:rst:leading-asterisk and endrst=\\endverbatim ^^ \endinternal.
We then built Doxygen twice, once to be used by Breathe, where we set the Doxyfile variable INTERNAL_DOCS=NO, and a second time to be used by doxysphinx, where we set INTERNAL_DOCS=YES.
In this way, the Doxygen documentation embedded by Breathe does not have the rst block inside and Sphinx throws no problems.

[mb-emag]

Thanks for reporting this issue! We'll try to fix that in our next iteration.

However here's a workaround which might help you in between:

If you use a path as INPUT-parameter for doxysphinx instead of a doxyfile the validation is skipped completely (see https://boschglobal.github.io/doxysphinx/docs/getting_started.html#build - INPUT-parameter) and your settings should work.

So instead of calling
doxysphinx build <SPHINX_SOURCE> <SPHINX_OUTPUT> YOUR_DOXYFILE
please try to use
doxysphinx build <SPHINX_SOURCE> <SPHINX_OUTPUT> YOUR_DOXYGEN_HTML_OUTPUT_PATH

[twodrops]

The validator shall be removed as part of #74

[mb-emag]

fixed in v3.1.0 (81546a7)