Support local namespace scope lookup

[arwedus]

Hello,

first of all thanks for this awesome extension to Sphinx.

I would like to set a namespace like with the .. cpp:namespace:: my_namespace directive.

Example.h

namespace my_namespace {
/// A class that I want to see in the Sphinx documentation
Class Foo;

/// A class I'd rather not see in the Sphinx documentation
Class Bar;
}

index.rst:

Class documentation
================

.. cpp:namespace:: my_namespace

.. doxygenclass:: Foo
   :members:

Now, this throws an error in my case.

Use case: I use the manual selection of the classes I actually want to have in the documentation exclusively (for "autogenindex" I could have also used Doxygen ;-)). Thus, I have more than a few breathe directives in a RST document, and repeating the namespace for every directive is repetitive.

Steps to reproduce

Breathe version: 4.27 Sphinx version: 3.5.1 doxygen version: 1.8.13

[jakobandersen]

I'm not sure there is any functionality to do what you would like at the moment. There are two entities in play here:

• the current scope of the C++ domain in Sphinx. The cpp directives modifies this one.
• how Breathe performs lookup in the Doxygen XML. They may be a way to prepend a namespace here, but I don't remember seeing it.

Breathe doesn't read the C++ domain scope and uses it for anything, and I think it would be tricky to get right before some other issues are resolved regarding the directive handling where it needs to figure out which programming language it is dealing with (I forgot the specific Github issue). Besides, there is a use-case for separating the scope from the lookup, to pretend the namespacing is different than in the real code. My immediate suggestion is that Breathe should have a new directive, lookup-prefix or similar, which sets the current scope for XML lookup, which is then stripped from each search result before running the Sphinx directive.

[arwedus]

@jakobandersen , I second your suggestion. Something like this would work just fine:

.. no local scope entered yet

.. doxygenclass:: my_namespace::Bar

.. doxygenprefix:: my_namespace

.. in local scope my_namespace::
.. doxygenclass:: Foo

[jakobandersen]

Indeed, except in the second example Sphinx would not declare my_namespace::Foo but just Foo, so a .. cpp:namespace:: my_namespace is needed in addition to the doxygenprefix.

[AlCash07]

I also encountered this issue when trying to manually order the namespace contents.

I tried doxygenprefix, but looks like it's not implemented yet.