add inline rst feature

[mb-emag]

Finally the first working implementation of the rst inline feature (which was way harder to implement than i initially thought)

[twodrops]

Wow, thats really a lot of changes and great documentation update. I did not manage to test it. I will do it once I am back from my vacation. Thanks @mb-emag

[Gnomiro]

Hello,

I came across this PR while trying to understand how to link to an rst-file inside from doxygen while using doxysphinx.

Please forward me to the right place if this is not the correct place to ask! :)

We are currently undergoing evaluations of possible ways to use doxygen with sphinx. I like to support breathe/exhale as well as doxysphinx for know and decide later which of these will be used. So far it works well side by side and I can get most links to work easily (from rst to doxygen resp. exhale-generated files) but I have troubles doing this with links from doxygen to the rst-documentation.

We are using doxysphinx 3.1.0.

The following doxygen syntaxes are handled totally different by doxysphinx and breathe/exhale.

What is the reason for this totally different behaviour? In a ticket (#73) I read that you had some troubles because of ` and others but in exhale/sphinx they seem to be able to parse it quite good and also support linking with :ref:.

Doxygen source:

/// @verbatim :ref:`Metaprog (breathe/exhale1)<oml_utility_metaprog>`@endverbatim.
/// :doc:\`Metaprog (breathe/exhale2) </source/utility/metaprog>\`
/// :doc:\`Metaprog (breathe/exhale3) <../../source/utility/metaprog>\`
///
/// <a class="reference internal" href="../../source/utility/metaprog.html">Metaprog (doxysphinx1)</a>
/// <code>:doc:\`Metaprog (doxysphinx2)</source/utility/metaprog>\`</code>
/// <a class="reference internal" href="../../source/utility/metaprog.html"><span class="doc">Metaprog (doxysphinx3)</span></a>

Breathe/exhale output:

:ref:`Metaprog (breathe/exhale1)<oml_utility_metaprog>` 
:doc:`Metaprog (breathe/exhale2) </source/utility/metaprog>` 
:doc:`Metaprog (breathe/exhale3) <../../source/utility/metaprog>`

Metaprog (doxysphinx1) 
``:doc:`Metaprog (doxysphinx2)</source/utility/metaprog>``` 
Metaprog (doxysphinx3)

Doxysphinx output:

<div class="fragment">
  <div class="line">
    :ref:`Metaprog (breathe/exhale1)&lt;oml_utility_metaprog&gt;`
  </div>
</div>
<p>
  :doc:`Metaprog (breathe/exhale2) &lt;/source/utility/metaprog&gt;` 
  :doc:`Metaprog (breathe/exhale3) &lt;../../source/utility/metaprog&gt;`
</p>
<div class="doxysphinx-inline-parent">
  <a href="../../source/utility/metaprog.html" class="reference internal">
    Metaprog (doxysphinx1)
  </a>&nbsp;
   
   :doc:`Metaprog (doxysphinx2)</source/utility/metaprog>`
   
   .. raw:: html
   
      <a href="../../source/utility/metaprog.html" class="reference internal">Metaprog (doxysphinx3)</a></div><dl class="section author">

Would it be possible to provide a common way of parsing/translating a link? Do I oversee the appropriate solution?

[twodrops]

@Gnomiro Thanks for trying out Doxysphinx.

Please forward me to the right place if this is not the correct place to ask! :)

There is no wrong place to ask questions :) So thats perfectly fine to ask here as long as we get a notification. You could also use the discussions section https://github.com/boschglobal/doxysphinx/discussions if you wish so that the discussions are visible for others as well.

@mb-emag will be back next week and he could clarify this issue.

[mb-emag]

Hi @Gnomiro,

The problem here is that breathe and exhale parses doxygen xml output and renders then the classes functions etc. on its own.
So it has full control over the output because it has access to the raw comments.

Doxysphinx on the other hand parses doxygen's html output - this keeps the doxygen look and is faster. However that means that doxygen has already parsed the comments and has build up an html structure out of the comments. So e.g. backticks will be interpreted as markdown verbatim content by doxygen and rendered as <code> or <verbatim> content. This ultimately creates a html structure that we cannot segmentize in a way that we can keep the "inlineness" of the content, at least not without really complex pattern matching/parsing. So to see the problem you have to look at the original doxygen html output.

One reason while we developed doxysphinx was the performance which isn't that good with breathe/exhale on very huge projects. Doing such a pattern matching over the complete html content will bring a hard performance hit (because we would need to pattern match the html tree and rewrite it in a preprocessing step).

So I fear that we will never be able to support breathe's inline syntax.

@twodrops we can talk about this topic in our next technical sync (next month) - I think this is really a hard problem but it might be worth the (for sure) hard work there.

I created a feature request for that topic #87 to better keep track of it.

[Gnomiro]

Ok. Thanks for the information :)

If there is no easy way for having a two-way solution at the moment we will probably just use doxysphinx.

But for an easier switch it would probably be great to provide a way for easier migration like suggested in the future request you created.