Add a mechanism for generating a list of members for a class, struct, etc.

[jo3w4rd]

The member list should by hyperlinked to the member documentation generated by the breathe directive.

Either making this an option of the directive that generates the class/struct doc or a separate directive would work for my purposes.

[jakobandersen]

This would be a very nice feature, and I have wanted to implement something like it in Sphinx for quite some time. I don't know much about the internals of Breathe, but I suggest to add a .. cpp:synopsis:: directive in Sphinx, and then options on the Breathe directives to auto-insert a synopsis, e.g., in classes.

[vermeeren]

It appears that this issue is very much like #362, at least at first glance. Could someone else confirm (or deny) that that is indeed the case?

[jo3w4rd]

Sounds essentially the same.

[vermeeren]

@jakobandersen I believe that what you proposed would be the cleanest solution when it comes to implementation.

An alternative solution I thought it was that breathe would generate labels for every directive, which would also fix #373, and then have a breathesynopsis or similar that will refer to those labels.

I do worry that that will generate an absurd amount of labels in big projects, which may cause label conflicts.

---

An example use case:

Some API docs generated by breathe-apidoc:

File add.h
==========

.. doxygenfile:: add.h

Rendered as:

Then somewhere in other doc, you could write something like:

Software architecture
=====================

Arbitrary text here. The subsystem overview for adding 8-bit unsigned integers is shown below.

.. doxygensynopsis:: add.h

Which would render as something like:

Clicking on add (C function) will then send you to the first screenshot's location.

This example is styled similar to the genindex page, but of course it could be different. We could also render the full signature as in uint16_t add(uint8_t a, uint8_t b).

@rowanG077 please check that this matches what you'd like to see (#362).

---

Most likely the best way for this is indeed to also add something in sphinx for a selective domain-synopsis. Not entirely sure though.

[rowanG077]

The doxygensynopsis directive is different from what I wanted to achieve with #362. doxygensynopsis is cool when you for instance want to generate a list of all functions in a file or a large index which is alphabetically sorted. But what I mean is that you can literally put in the declaration in your rst files with some options and it wil render the declaration not just a short text but literally what is also in the api doc.

Imagine that you have a matrix class and you are talking about an algoritm. It would be really nice then to render the inline declaration (which means including params and return type) of the method that implements that algoritm.

[vermeeren]

Would that inline declaration need to point to the full API docs? Or should it only render what you specify?

In the latter case I believe it is already possible with available directives. As for the "duplicate declaration" warning, I believe that the no-link attribute that can be passed to Breathe directives will prevent it from telling Sphinx that this is where references should link to. See also #378. (I see you just commented on that, so this comment might be obsolete already.)

[rowanG077]

Yes that inline declaration should point to the full declaration in the API docs. It should also only render what I specify. So I could say render this class only with this member. But the link would still point to the full declaration.

[jakobandersen]

I think we need two related mechanisms on the Sphinx side:

• The alias role/directive which in some form renders a declaration without redeclaring it. My current thought is that it should basically be like how forward declarations look (but some customization could be done via options to directives). The name of the entity would be a link to the actual declaration.
• The synopsis directive, which requires the ability to list all symbols in a given scope. Each declaration is the essentially rendered with the alias directive/role. This is a can of worms with respect to options as people might want arbitrary filters for which entities are listed, and how they are sorted.

I have an old prototype for both features somewhere that I will try to make work again.

[vermeeren]

@rowanG077

So in the other doc, you would write something like:

.. doxygenfunction:: add
    :ref:

Which would then render something like:

In this screenshot, the uint16_t add(uint8_t a, uint8_t b) is clickable and link to full API docs. Is this what you'd like or am I missing something?

The issue I see with this is that because the entire signature is a link it becomes blue, with hurts readability. We should probably come up with a better design than this.

[rowanG077]

Well the heading itself doesn't have to be a link. There could also be a link after it. But I don't mind it being blue. You can always customize this yourself easily using css.

But yes +1 for separating the features they are different.

[vermeeren]

@jakobandersen that does seem like a good idea, I suppose Breathe in this case can then add :alias:, or similar, to all directives so an user could write like two comments above with :ref:.

Also tagging upstream so the ref registers: sphinx-doc/sphinx#4981

[orlandini]

Any updates on that?

[Gnomiro]

Any news on a feature like this? Would love to reference to functions while showing their documentation again.

Showing documentation again with calls like

.. doxygenfunction:: add
:ref:

while providing a link to the original file would be awesome!

[ReenigneArcher]

This has been open for a while. At a minimum could you add a config option to suppress specific warnings?

Someone tried to add the warning types to sphinx, but they rejected it. sphinx-doc/sphinx#7851