Add support for \parblock parsing and rendering

[utzig]

Add support for using the \parblock command from Doxygen: https://www.doxygen.nl/manual/commands.html#cmdparblock

This command can be used to generate multiple paragraphs from simple text inside the section. It's most useful for grouping text in Doxygen aliases.

[utzig]

@vermeeren I hadn't even noticed someone already reported this! I just tried to create a Doxygen ALIAS today using \parblock and the rendering came back empty! :-)

[utzig]

@vermeeren I hadn't even noticed someone already reported this! I just tried to create a Doxygen ALIAS today using \parblock and the rendering came back empty! :-)

Also notice that the parsing of the contents of the <parblock> itself should be fine, but for my particular case the <parblock> was created inside a <para>, so I only updated the "para" parsing with it. This means this PR may not fix the issues mentioned because they mention \parblock inside \param. But it surely does make it much easier to fix those afterwards; I can take a look at this.

[utzig]

@vermeeren I hadn't even noticed someone already reported this! I just tried to create a Doxygen ALIAS today using \parblock and the rendering came back empty! :-)

Also notice that the parsing of the contents of the <parblock> itself should be fine, but for my particular case the <parblock> was created inside a <para>, so I only updated the "para" parsing with it. This means this PR may not fix the issues mentioned because they mention \parblock inside \param. But it surely does make it much easier to fix those afterwards; I can take a look at this.

@vermeeren Indeed using \parblock for documenting \param also creates a <para> around the <parblock> (inside the <paramterdescription> block) so this PR should fix #372 as well.

[vermeeren]

@utzig Thanks again for all your work. Should I take a look at reviewing this or is there something you'd like to check first?

[utzig]

@utzig Thanks again for all your work. Should I take a look at reviewing this or is there something you'd like to check first?

Yes, go ahead, I have no other updates as of yet, I was only in doubt about the usage with \param which seems to work fine, so this should be OK as is.

[vermeeren]

@utzig All good, merged. Should I release a new version?

[utzig]

@utzig All good, merged. Should I release a new version?

Right now I don't need it, I used this to implement a PoC for something which we aren't sure yet when it will land. I'll ping you here if it turns into something we need.

In the meantime I was looking at a few issues for which I plan to submit patches for, so those may also be put all together in a new release.

Btw, maybe you should consider doing alphas, betas and so on. So instead of releasing a stable release every time, you just push a beta to pypi and a user can get with pip install --pre, but it is not installed when just using pip install -U. This allows for some test time (as long as there are people using it!), as well as avoids exhausting release numbers!

[vermeeren]

@utzig Sounds good to me, thanks!

I have been thinking about alpha/beta quite a while ago, but I find Breathe is mostly in maintenance mode right now with some smaller features sometimes added by contributors like you, so it's mainly fixes and compatibility updates with new Sphinx currently. Personally I don't think it's worth using alpha/beta for this type of development, though I will definitely reconsider if/when more major development is done. There are some vague plans for a Breathe 5 one day.