How to render Doxygen xml output into markdown instead of reST (using MyST-Parser)

[atifkarim]

In summary, my desire: is to know is it possible to fetch Doxygen XML output and dump them in .md file using MyST-Parser?

• Fetching of Doxygen XML output and dump them in .rst file is done by breathe.

I am preparing a project documentation using Sphinx where to fetch Doxygen XML output I have used breathe. I am using the breathe directive in .rst files.

I am using:
Sphinx version : 4.2.0
Doxygen version: 1.8.17
Breathe version: 4.31.0

sample.cpp

namespace X{
class A{
   public:
       int x;
};
}

in my rst file I just added

.. doxygenclass:: X::A
   :members:
   :protected-members:
   :private-members:

After building the project I can see detailed documentation of class A. For some reason, I have the intention to use the markdown file instead of .rst. At that time I have seen myST-Parser in Sphinx Doc.

But, I was unable to catch the Doxygen XML output as like as done by breathe. I have gone through several posts but could not find any fruitful answer. The best one I have got this StackOverflow answer.

• I have installed myst parser
• Modified conf.py by adding extensions = ["myst_parser",]

Written a .md file as like as follows:

# sample_md
```{doxygenclass:: X::A}
:members:
:protected-members:
:private-members:
```

But failed while the error message is

WARNING: unknown directive or role name: doxygenclass::A
/net/users/Linux_Home/user_name/project_name/doc/md_files/sample_mark.md:5: WARNING: Unknown directive type "doxygenclass::A".

Also tried

# sample_md
```{doxygenclass}
A
:members:
:protected-members:
:private-members:
```

Failed too and the error message

Exception occurred:
  File "/net/users/Linux_Home/user_name/.local/lib/python3.8/site-packages/myst_parser/docutils_renderer.py", line 973, in run_directive
    if issubclass(directive_class, Include):
TypeError: issubclass() arg 1 must be a class
The full traceback has been saved in /tmp/sphinx-err-guubfd6h.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make[2]: *** [doc/CMakeFiles/Sphinx.dir/build.make:63: doc/sphinx/index.html] Error 2
make[1]: *** [CMakeFiles/Makefile2:215: doc/CMakeFiles/Sphinx.dir/all] Error 2
make: *** [Makefile:130: all] Error 2

I have used following snipet in .md file

```{cpp:class} X::A
```

which has shown rendered class but only the name with a clickable link where no documentation of Doxygen XML is present. And I need that info.

No idea what to do at this stage.

Some of my observance:

• myST is only for collecting Sphinx directive in markdown file
• breathe is a tool to fetch Doxygen XML output and to write in reST style using Sphinx

Now my desire is to know, is it possible to add Doxygen XML output in the .md file? If Yes, where am I am making the syntax wrong?

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[chrisjsewell]

Heya, so firstly to note the syntax should look like:

```{doxygenclass} X::A
:members:
:protected-members:
:private-members:
```

But I think there may still be some issues with using breathe directly, which does some "non-standard" things: #322, #323

As mentioned in thos issues though, I think the workaround is to use the eval-rst directive:

```{eval-rst}
.. doxygenclass:: X::A
   :members:
   :protected-members:
   :private-members:
```

[atifkarim]

Thaks @chrisjsewell , it has solved my issue. By the way, I am having another issue now related to cross reference.

For Example I have now chosen the mentioned class

sample.cpp

namespace X{
class A{
   public:
       int x;

      /// This will do priniting task
       void Print_Message();
};
}

While I have written Doxygen directive in rst files

.. doxygenclass:: X::A
   :members:
   :protected-members:
   :private-members:

I can easily link the class and it's any member as like as follows:

• crossref class approach 1:

Click here to go :cpp:class:`X::A`

This [:cpp:class:X::A] part is aligned in a box that is clickable

• crossref class approach 2 (custom text):

Click here to go :cpp:class:`CUSTOM_NAME <X::A>`

This [:cpp:class:CUSTOM_NAME <X::A>] part takes the string CUSTOM_NAME which is clickable

• crossref function of a class

Function is :cpp:func:`this <void X::A::Print_Message()>`

This gives me a string this which is linked to Print_Message function.

Unfortunately, I am not finding any way to do it using myST. I have done in my markdown file is as follows

sample.md

(section_class_A)=
```{eval-rst}
.. doxygenclass:: X::A
   :members:
   :protected-members:
   :private-members:
```

In the markdown file later I have written

Grab {ref}`Dummy_Class_A <section_class_A>`.

• Is there any way to do cross-reference without adding this section tag/label/ref label? Like:

Grab {ref}`Dummy_Class_A <:cpp:class:`X::A`>`
or,
Grab {ref}`:cpp:class:`X::A``

I know that the above two are not working.

• Is there any way to cross-reference the member function?
• My intention to cross-reference function is not do something like

```{eval-rst}
:cpp:func:`this <void X::A::Print_Message()>`
```

as by this all desired target is not placeable in 1 line.

I have no clue how to achieve those.

[chrisjsewell]

Note, this in rst:

Function is :cpp:func:`this <void X::A::Print_Message()>`

In myst is just:

Function is {cpp:func}`this <void X::A::Print_Message()>`

Does that solve your question?

[atifkarim]

@chrisjsewell thanks a lot, It has solved my question.

• By the way, to use any sphinx directive using myST is the rule is like as follows?
  If the directive is written in reST file as :sphinx_directive: in myST it will omit the colon sign : and will be

{sphinx_directive} `arg`

or something else?

• Maybe I have missed the doc, can you please point here where the rule is written (to convert any Sphinx directive to myST)? As I have not found the rule to use

{cpp:func}`this <void X::A::Print_Message()>`

I believe that I have missed most important parts somehow. Still I am reading but could not get the point.

[chrisjsewell]

https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point

[jakobandersen]

Note, the Breathe issue (#460 (comment)) should be fixed in the next Breathe release.