Breathe as a source of C++ items, with the documentation in .rst?

[LiliumAtratum]

I am trying to use Doxygen + Sphinx + Breathe in my probject, but I feel I am doing it wrong.
I wanted to use Breathe as a source of C++ declarations, while keeping the documentation in the .rst file itself.
So, for example, if I have a MyClass class with two methods foo and bar it looks like this:

.. doxygenclass:: MyClass
   :members: foo
   :undoc-members:
   :no-link:
   :members-only:
   
Documentation of MyClass::foo in .rst   

.. doxygenclass:: MyClass
   :members: bar
   :undoc-members:
   :no-link:
   :members-only:
   
Documentation of MyClass::bar in .rst

but there are several issues that hint me that this is not the intended approach: the documentation is not indented, I get a bunch of warnings WARNING: Duplicate C++ declaration and it seems overly verbose in the .rst file.
Moreover, when I try to indent the documentation to match the directive, I get an error: ERROR: Error in "doxygenclass" directive: no content permitted.
Same problem appears if I try to document free functions.

[jakobandersen]

I wanted to use Breathe as a source of C++ declarations, while keeping the documentation in the .rst file itself.

If I understand you correctly, then I don't think this is possible at the moment. Can you elaborate a bit on the use case? If you anyway write all the documentation in the rst-files, then writing the declarations manually using the underlying Sphinx directives doesn't seem much of an overhead to me. E.g.,

.. cpp:function:: void MyClass::foo(int arg)

   Documentation of MyClass::foo in .rst

As for your concrete example, if you only want to extract a single member function I believe it should be possible:

.. doxygenfunction:: MyClass::foo

The "no content permitted" error is because the content is supposed to be extracted from the Doxygen XML, so the Breathe directives explicitly disable content. If there is a compelling use-case I think it should be possible to allow additional content.

The "Duplicate C++ declaration" error is fundamentally because the same declaration has been extracted multiple times and put through to Sphinx. Each class, function, variable, etc. can only be documented once. I think the best strategy is to first make the rst such the output is how you like it, and if this still appears then dive into specifics.

[LiliumAtratum]

Writing the declarations in Sphinx directives manually is a viable fallback solution, but it is repetition I was hoping to avoid. When using Doxygen+Breathe I ensure that the entry really exists in the sources and matches the definition in the documentation. And if it is not in the sources - I get an error message. Obviously, it won't fix every possible scenario where documentation gets out of sync with the sources, but makes a big step towards detecting this, at least at the basic level.

The doxygenfunction solution you suggested does not seem to work however. I get: WARNING: doxygenfunction: Cannot find function "void MyClass::foo" in doxygen xml output for project. My guess is, that Breathe searches only for free functions?

I understand where the duplication is coming from, and probably I will just ignore it. The no-link description explicitly considers a scenario with repeated directives, so this is not something unheard of. I mention it because it gave me another reason to think that I am not doing the documentation in the right way.

In the end I will probably keep short explanations of particular functions and methods in doxygen commens and document in Sphynx when bigger examples come in.