Scoped rendering

[jakobandersen]

The Short Version

Implement the idea sketched in #354 (comment):

• Use a new mechanism in Sphinx to render content in the scope of a directive.
• Instead of using the definition XML, and construct a fully qualified name,
  construct the declaration string from other parts of the XML.
  The qualification is now provided by the previous point.

The Slightly Longer Version

When processing the rst

.. cpp:class:: A

   .. cpp:var:: int i

Sphinx will run the class directive with A and then in a nested parse eventually run the var directive with int i. The C/C++/Python domains then handle the scoping of i inside A.
Breathe was created before this scoping mechanism was implemented, and thus worked around it by executing a hybrid of

.. cpp:class:: A
.. cpp:var:: int A::i

with respect to the domains, but rendered as if the variable was nested in the class directive. Breathe then removes the A:: part by manipulation of the doctree.
In order to construct the fully qualified name for i the definition tag in the XML is used. However, the content of this tag is not always correct. For example, many of the problems with templates is due to this, and the function pointer reshuffling is as well.

This PR changes the rendering such that Breathe renders the content of a directive as if it was the result of a nested parse, meaning the fully qualified name is no longer needed. The declarations are therefore now stitched together using other parts of the XML.

Changes (apart from the scoped rendering)

• Enumerators are now prefixed with "enumerator" as in Sphinx.
• Switches from deprecated PyModulelevel directive to PyFunction.
• Fixes issue with false typing of Python function arguments
  (e.g., __init__(self self).
• Switches from deprecated PyClassmember directive to PyAttribute.
• Fix rendering of initializers for Python attributes.
• Fix display of Python modules, namespace -> module.
• Render friend classes as textual elements instead of as a declaration.

Testing

I have only tested with Breathe it self and a few repro projects mentioned in issues.

Fixed Issues

Issues that I have tested to be fixed with this PR:

• Problems with type aliases inside template #284, Function arguments are getting shuffled around #309, noexcept not rendered #338, help me fix the full template specializations? #354, Duplicate IDs when using INLINE_INHERITED_MEMBERS=YES #356, Spurious "Too many template argument lists compared to parameter lists" error #407, "WARNING: Duplicate declaration" for enum class members  #470, C domain generation doesn't work with Breathe v4.12+ #483, Bug in generated HTML when using function pointer inside a struct #489
• Bug with trailing return types for c++ source code #441 (fixed, but Sphinx does not support trailing return types yet)

Perhaps Fixed Issues

Issues with a good chance of being fixed by this PR, but not confirmed:

• Showing a function in index as C instead of C++ #282
• How to improve documentation of C structs with anonymous types and members? #369
• Spurious "duplicate declaration" error with class members #406
• Spurious "Error in type declaration" #408
• :cpp:enumerator: not linking to the enumeration value #437
• Partial template specialisation in a namespace #442
• dropping enum member of struct, just showing type #447
• Breakage with restrict qualifier #477

TODOs for the future(?)

• Scoped enums do not seem to be differentiated from unscoped in the Doxygen XML.
• Templated type aliases do not seem to have a template parameter list in the Doxygen XML.
• For classes that are partial specializations, if one of the arguments contain
  :: the name extraction will probably fail.
• Friend classes should probably use CPPExpr to get an xref, but its
  construction requires some arguments that I'm not sure how to immediately get
  (perhaps from the context object?).
• The PHP support has not been updated (its domain has not been updated to 3.0,
  and there are no test cases). Once done, a lot of old code can be removed.
• Breathe injects additional an additional ID in each declaration, based on the
  one in the Doxygen XML. I'm not not where these IDs are actually used.
• It looks like the doxygenfunction directive results in
  Duplicate declaration warnings. I believe the problem is that Breathe
  renders function declarations twice, once to figure out if the function
  is actually selected by the directive (directives.py:237), and then
  secondly to actual rendering into the output. The first round is discarded.
  Instead of the full rendering it may be possible to use the Sphinx C++ parser
  directly to essentially do the same trick.
  My best guess is that this is the issue reported in Duplicate declaration warning for overloaded functions #504.
  It looks like this PR breaks the current trick when function templates are
  involved.

[vermeeren]

This looks like it might also fix #511. I will try to properly review this within a few days, need to find a timeslot to take a good look at this.

On a side note, does this need Sphinx >= 3.0 still or is scoped rendering something from 3.1.x or similar future version?

[jakobandersen]

This looks like it might also fix #511.

It will at least change the result, but if I remember correctly there is something icky with the Doxygen XML and anon unions.

On a side note, does this need Sphinx >= 3.0 still or is scoped rendering something from 3.1.x or similar future version?

It should work with >= 3.0.0.

[5p4k]

Hello. I'm encountering a bunch of errors when running Exhale + Breathe on my C++ project (planning to open an issue); I'm posting here because this PR fixes a lot of them, and maybe this can help identify duplicates or other potential issues that can be fixed.

Fixed by this PR:

• "Invalid C++ declaration" when using templated unions
• "Error when parsing function declaration" when befriending other classes. This is a weird one because it occurred only if the access modified was inserted (e.g. public:).
• "Too many template argument lists" with a using statement referencing a template. Also occurring when there is an access modifier.
  I think it's the same as #407 or #284.
• "Duplicate declaration" when using a non-const parent's method. This is also odd in the sense that const method did not trigger it.
  I think it's the same as #356.

Link to the log file.

[vermeeren]

I am almost ashamed only posting some pedantic style inconsistency comments. Still, Everything else seems fine to me. @jakobandersen I intend on merging after the two comments are handled. Thanks again.

[vermeeren]

@LizardM4 thanks for posting other related issues, will handle those too.