missing support for \par (or maybe ALIASES?) about breathe HOT 11 CLOSED

Hi,

Thank you for reporting it and for such clear example code. Made it a dream to debug and fix.

I've pushed some code which should handle the \par case more appropriately. It was generically handling the "simplesect" nodes in the xml in the same way, so there might be other cases where it results in less than idea behaviour!

Thanks again,
Michael

from breathe.

Great! Thanks for continuing to be so responsive to bug reports.

Best,
Marti

from breathe.

Looks like a regression reintroduced the old behavior; see "Alias example" in /testsuite/source/specific.rst

from breathe.

Hey,

Yeah, seems that it got washed away with a change a couple of months ago. I've just pushed some changes that should re-instate it. I should probably get some proper regression tests together that generate specific output and diff it against known values. Instead of pretending that the docs are some kind of testsuite :)

Ah well, another day! Thanks for noticing this,
Michael

from breathe.

Hello again,

Thanks for fixing this! Sorry I didn't close it. One minor wrinkle: it looks like you're appending an extra ":" at the end. The output is currently "Side Effects::" instead of the desired "Side Effects:". Doxygen says you should put the ":" yourself when defining the alias, so there's no need for Breathe to add it:

# This tag can be used to specify a number of aliases that acts 
# as commands in the documentation. An alias has the form "name=value". 
# For example adding "sideeffect=\par Side Effects:\n" will allow you to 
# put the command \sideeffect (or @sideeffect) in the documentation, which 
# will result in a user-defined paragraph with heading "Side Effects:". 
# You can put \n's in the value part of an alias to insert newlines.

from breathe.

Thank you Marti, I'll up date that and hopefully we can close this.

from breathe.

Hey, this isn't as trivial as I hoped. We're not explicit adding ":" but at some points interpreting these entries as field lists for rst which then adds the ":" itself. It feels like a good match for parameter and return entries which get processed this way but not for some other types so there is going to have to be some effort to recognise when it is and isn't appropriate.

I'm not managing to make much time for this but I'll hopefully get it sorted over the next week or so.

Michael

from breathe.

On 05/30/2012 03:58 PM, Michael Jones wrote:

Hey, this isn't as trivial as I hoped. We're not explicit adding ":"
but at some points interpreting these entries as field lists for rst
which then adds the ":" itself. It feels like a good match for
parameter and return entries which get processed this way but not for
some other types so there is going to have to be some effort to
recognise when it is and isn't appropriate.

Wow, sorry to hear it's such a pain. Thanks for looking into it.

I'm not managing to make much time for this but I'll hopefully get it
sorted over the next week or so.

It's easy enough to just not include the ":" in ALIASES, so at least
there's a workaround. Given that, it's no trouble if you treat this as a
low priority bug (maybe it's possible to submit it as an upstream issue?).

Thanks,
Marti

from breathe.

Hey,

I had the idea to check the doxygen output to see how they handle (embarrassing that I've not done this before!) and they output them as definition lists so I've matched that and the results look pretty reasonable and importantly the same as the doxygen standard stuff.

I've pushed the changes. I've not tested super rigorously but the examples all run and it seems to give better output in these user \par situations.

Please give it a go and see if it helps :)
Michael

from breathe.

On 05/31/2012 04:39 PM, Michael Jones wrote:

Hey,

I had the idea to check the doxygen output to see how they handle (embarrassing that I've not done this before!) and they output them as definition lists so I've matched that and the results look pretty reasonable and importantly the same as the doxygen standard stuff.

I've pushed the changes. I've not tested super rigorously but the examples all run and it seems to give better output in these user \par situations.

Please give it a go and see if it helps :)

Will do; thanks!

Michael

---

Reply to this email directly or view it on GitHub:
#15 (comment)

from breathe.

Closing as it seems to be resolved. Reopen if desirable!

from breathe.