[request] support Sphinx directive seealso

[2bndy5]

I was wondering why note & warning admonitions from doxygen were properly translated into the rst equivalent directives, but this isn't the case for the seealso directive. After some research I found that Sphinx defined their added seeaso directive in addnodes.py (a module already imported in sphinxrenderer.py).

So, I was able to implement this with 2 added lines of code in sphinxrenderer.py: https://github.com/michaeljones/breathe/blob/327374db4cc440bec39dd4c6f96471035aa56317/breathe/renderer/sphinxrenderer.py#L1545-L1548 with the added

        elif node.kind == 'see':
            return [addnodes.seealso('', *nodelist)]

results

without changes to sphinxrenderer.py

with changes to sphinxrenderer.py

Please excuse the CSS styling as that was done specifically for my project. Typically the seealso directive renders the same as a note admonition (except that the admonition title says "See also" instead of "Note").

I don't know if this is a feature that has been already discussed (the closed issues are lengthy), so please excuse my arrogance if this request has already been previously denied.

Additional context

According to the doxygen docs, the @see and @sa are synonymous. The XML output for each cmd concurs. Both @see and @sa cmds render in XML as

<simplesect kind="see">
...
</simplesect>

[2bndy5]

I was wondering if there are any objections to rendering <simplesect kind="remark"> as generic admonitions. This would more easily allow users to add their own CSS styles for the @remark cmd (which is currently indistinguishable in HTML from parameter lists).

[2bndy5]

ok I'm also able to admonish @remark and @remarks cmds as generic admonitions by adding the additional lines (to the visit_docsimplesect() function in _sphinxrenderer.py)

        elif node.kind == "remark":
            nodelist = [nodes.title("", nodes.Text(node.kind.capitalize()))] + nodelist
            return [nodes.admonition("", classes=[node.kind], *nodelist)]

Note: This adds a class remark to the generated HTML elements for easy CSS overrides.

Results

without changes

with changes