Python 3.8.5 renders '**irc.abort**' as invisible: '<strong></strong>'

[6r1d]

Hello. I am copying this issue from Sphinx, since it seems it's related to Breathe. Initial issue is located there. The project to reproduce the issue is located here.

Python 3.8.5 renders **irc.abort** as invisible: <strong></strong>

**sirc.abort** is rendered correctly as: <strong>sirc.abort</strong>

Somehow newer python seems to detect **i as something special. I have tried escaping with **\i without success.

Reproduction process is described in the readme file at https://github.com/SwissalpS/sphinxBugIsolation

Environment info

• OS: Linux Fedora 32
• Python version: 3.8.5
• Sphinx version: 3.2.1
• Sphinx extensions: exhale, breathe, groundwork
• Extra tools: [Browser]

Additional context The bug seems to be related to a Python version. (It seems the older Python version works as intended.)

*Screensots Expected behavior:

[6r1d]

I forgot to copy @jakobandersen's comment, but it is probably very useful to add here!

there is a high chance that the problem is somewhere in Doxygen / Breathe. From the Doxygen XML (namespaceSwissalpS_1_1FooTest_1_1IRC.xml):

...
<briefdescription>
    <para>called from lua by <bold>core.abort</bold>(iNumber) as <bold><ulink url="irc.abort">irc.abort</ulink></bold>(iNumber) </para>
</briefdescription>
...
<briefdescription>
    <para>called from lua by <bold>core.bort</bold>(iNumber) as <bold>sirc.abort</bold>(iNumber) </para>
</briefdescription>
...
<briefdescription>
    <para>called from lua by <bold>core.ort</bold>(iNumber) <bold>as <ulink url="irc.abort">irc.abort</ulink></bold>(iNumber) </para>
</briefdescription>
...

I guess there is an issue with how the ulink tag is handled.

[6r1d]

I want to determine if it's Doxygen or Breathe itself. I will configure the bug isolation example to work verbosely while launching Doxygen.

exhale_args = {
    "verboseBuild": True,
}

Now, while I'm making an HTML build, I see this log:

[~] Exhale: executing doxygen.
[*] The following input will be sent to Doxygen:
# If you need this to be YES, exhale will probably break.
CREATE_SUBDIRS         = NO
# So that only Doxygen does not trim paths, which affects the File hierarchy
FULL_PATH_NAMES        = YES
# Nested folders will be ignored without this.  You may not need it.
RECURSIVE              = YES
# Set to YES if you are debugging or want to compare.
GENERATE_HTML          = NO
# Unless you want it...
GENERATE_LATEX         = NO
# Both breathe and exhale need the xml.
GENERATE_XML           = YES
# Set to NO if you do not want the Doxygen program listing included.
XML_PROGRAMLISTING     = YES
# Allow for rst directives and advanced functions e.g. grid tables
ALIASES                = "rst=\verbatim embed:rst:leading-asterisk"
ALIASES               += "endrst=\endverbatim"
# Enable preprocessing and related preprocessor necessities
ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = NO
SKIP_FUNCTION_MACROS   = NO
# extra defs for to help with building the _right_ version of the docs
PREDEFINED             = DOXYGEN_DOCUMENTATION_BUILD
PREDEFINED            += DOXYGEN_SHOULD_SKIP_THIS


INPUT = ../../src
RECURSIVE = YES
FULL_PATH_NAMES = YES
SHOW_FILES = YES
HIDE_IN_BODY_DOCS = NO
# this is set to NO if EXTRACT_ALL is set to YES
WARN_IF_UNDOCUMENTED = YES
# sometimes we just want all for valid reasons
EXTRACT_ALL = NO
# Allow for rst directives and advanced functions e.g. grid tables
ALIASES += "rst=\verbatim embed:rst:leading-asterisk"
ALIASES += "endrst=\endverbatim"

To continue, I want to know how to call Doxygen while passing these options manually, so I can install @SwissalpS doxygen version to compare its output to my local Doxygen. I tried copying the config from a log into a file and running it like doxygen doxy.conf, but it gave me only several files: combine.xslt, compound.xsd, index.xml, index.xsd. No namespace*.xml.

In my case, the Doxygen version is:

$ doxygen -v
1.8.13

[svenevs]

To debug / play with doxygen configs, since as you see I inject quite a bit of stuff there, advise just creating local Doxyfile in same directory as conf.py with the exact configs, exhale will run it from that directory

docs/
    conf.py
    Doxyfile

I over-engineered that, so double check your paths are correct, in example above exhale requires Doxyfile in docs directory and runs it from there too. Then in conf.py, get rid of the exhaleDoxygenStdin and set exhaleUseDoxyfile to true. You will probably have an easier time inspecting if you tell it to GENERATE_XML = YES (required for breathe etc) as well as GENERATE_HTML = YES to see what their html side looks like.

This one is a rather strange bug, but AFAICT the doxygen side is fine, and it seems more likely that something subtle has changed in 3.8 that we aren't aware of in the rendering code in breathe. I took a look at this briefly last weekend and intend to look more this weekend, but hopefully the above can enable you to make some progress in between then if only to confirm doxygen side looks OK :slightly_smiling_face:

The only thing that looks slightly fishy with the stdin approach you have right now is you're adding things in there that were already there. For example

# vvvv from exhale
# So that only Doxygen does not trim paths, which affects the File hierarchy
FULL_PATH_NAMES        = YES
# ... vvv from your exhaleDoxygenStdin config
FULL_PATH_NAMES = YES

That doesn't matter though, and it's also by design. If you had set FULL_PATH_NAMES = NO, Doxygen will use whatever that last value it sees is (why I add your configs at the end). Exhale should have given you a warning explaining the difference between = and += in doxy configs. So in this case, it's not needed since same value, but doesn't change anything. The only thing that might cause a problem (but doubt it causes this problem) is that the ALIASES are duplicated for \rst macro in doxygen. Hope that helps some!

[6r1d]

Thanks a lot, I see a lot of differences in Meld now! A notable one would be in namespaceSwissalpS_1_1FooTest_1_1IRC.xml.

Doxygen 1.8.13:

<para>called from lua by <bold>core.abort</bold>(iNumber) as <bold>irc.abort</bold>(iNumber) </para>        </briefdescription>

Doxygen 1.8.20:

<para>called from lua by <bold>core.abort</bold>(iNumber) as <bold><ulink url="irc.abort">irc.abort</ulink></bold>(iNumber) </para>

At the very least, ulink appears. I don't know if it qualifies issue to migrate again, though. 🙂

[svenevs]

Ah interesting, very helpful thanks! Can you share exact Doxyfile you were using? My doxygen is old and I didn't even think to look at this x0

I have docs stuff slated for tomorrow, I think to accommodate we will possibly want to either (a) prevent doxygen from emitting ulink (possible new feature?) or more likely (b) teach breathe about ulink and what to do. That may be quite involved though, it probably also relates to tagfiles and linking in general.

[6r1d]

Can you share exact Doxyfile you were using?

No problem, there it is, I think I copy-pasted it right from my recent comment. I thought it might be better to share both directories with differently rendered versions, too.

or more likely

Sounds good, thanks!