doxygenfile: only @file description

[ax3l]

Hi,

is there a way to select what is printed in doxygenfile:: besides :outline:?
Specifically for .. doxygenfile::, I would like to show

• only the @file description
• select: defined classes, typedefs, functions and/or enums

[ax3l]

What I found so far:

file options are set in directive/file.py and filtered by those options in renderer/filter.py - FilterFactory

One question is also how to name an only @file description filter or to add specific no-... filters to remove selected output instead.

[ax3l]

@michaeljones can you give me a hint if you support such an addition and how you would like to see it implemented? :)

[michaeljones]

Showing only the file description is a very reasonable request. In some ways it would make sense if that was the default which would bring it in line with the class directive (I believe.) We could then have a :members: field that could contain a list of what you want to display (or display everything if it is empty.)

I'm afraid I'm sufficiently out of the loop that I can't make any suggestions of the off of my head but I will attempt to dive into the code and get a better feel for it.

[michaeljones]

Thank you for your patience and for the ping.

[michaeljones]

Actually, it would be useful to know what you would like to see for the output if it was just the description. Currently Breathe does not output the file name or any kind suggestion that the target is a file and starts the output with the description. Would you want to see just the description or something more like:

---

file: MyFile.h

This is my file description and it goes on for a few sentences. Maybe.

---

ie. with some kind of 'header'.

[ax3l]

thank you for the reply!

for the last point: yes, I think unifying it to behave closer as the class macro:

• add the name of the file (as it adds the name of the class)
• add members only on :members: (or maybe called :content: for a file)

would be useful.

Currently I always add the name of the file + the macro which kind of doubles the effort (but I do the same for classes still, since I want the names to show up in my sphinx toc).

[vermeeren]

Based upon activity above I am pretty sure that this issue still exists, tagging it as such.

[lshamis]

Any updates on this?

[vermeeren]

Breathe has a shortage of contributors, so the only way to get this feature in the short term would be to write patches yourself.

[lshamis]

@vermeeren can you give me some file/line pointers where things would need to get updated?

[vermeeren]

@lshamis I did some quick grepping. See breathe/directive/file.py:66 for a starting point, which then points to (one of) the create_project_info() in breathe/project.py, I think the one on line 243 is relevant.

From here on the best way is likely experimentation with modifications and seeing how that influences the result, there is unfortunately no proper technical documentation for Breathe's internals.

[lshamis]

In #501 I added a :sections: options to the doxygenfile directive.
It takes a space separated list of sections as an argument, and renders only those sections, in the given order.

For example

.. doxygenfile:: nutshell.h
   :sections: briefdescription enum typedef

@ax3l For the @file description, you could use

.. doxygenfile:: nutshell.h
   :sections: detaileddescription

I think this covers most use cases. Thoughts?

[ax3l]

Sounds awesome! I love it!

[vermeeren]

If someone could check #501 (comment) and post some thoughts about that specific comment I would appreciate it, will make an upload after it is handled.

[vermeeren]

Reopening until fully handled, see comments in #501.

[vermeeren]

If some of you could review #509 and check if the doc makes sense to you I would appreciate it.

[vermeeren]

Breathe v4.16.0 has just been released containing the implementation of doxygen(auto)file section option and improved documentation for doxygen(auto)file in general. Unfortunately readthedocs sync is somehow broken, see #475. I added a screenshot below of the section option table. You can of course also make html in the Breathe repo yourself until doc deployments are fixed.

@alephzero thanks again for all the help for documentation improvements and checking everything is fine!