Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Resolve full title for doxygenpage and doxygengroup and allow for omitting the title all together #939

Open
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

RaumZeit
Copy link

@RaumZeit RaumZeit commented Jul 19, 2023

Currently, the doxygengroup or doxygenpage directives will render a line like

page page_id

or

group group_id

before the actual description and content, where page_id and group_id are the ids as specified in the corresponding doxygen commands, e.g.:

@defgroup   group_id   This is my group of functions
@page page_id  This is my page with some nice content

What one would rather have rendered in the .rst output is the full titles, not just the ids.
This set of patches addresses that problem by resolving the full title of the group or page if it is available in the doxygen xml ouput.

Moreover, the second patch introduces a new option for the doxygenpage and doxygengroup directives: no-title.
The purpose of this flag is to allow for leaving out just the title of a page or group, which is useful if the actual title is included in the .rst document that calls the directive. For instance:

My API group
------------
Below are all symbols related to this group of functions

.. doxygengroup:: group_id
    :no-title:

would render such that the description and content smoothly follow the text in the .rst file without any doxygen-specific title for group_id. Note, that when the group contains additional doxygen @name commands (member group names) that further sub-group the members of a group, they are still shown. So sub-grouping/member groups are still working as before.

I introduced the no-title option since when using content-only all sub-group names where lost together with the actual group/page title. But I wanted to keep the sub-group names while still leaving out the title.

I believe this option and the expansion to the full group/page title may be useful for others as well.

@RaumZeit
Copy link
Author

Just wanted to give this PR a ping...

We already successfully use these patches to build our software documentation. Our code is documented by doxygen and additional metadata is provided by separate sphinx .rst pages.
If the maintainers like, please have a look at the results that use the no-title option to seamlessly integrate both, .rst and doxygen page structures:

https://viennarna.readthedocs.io and sources are available at https://github.com/ViennaRNA/ViennaRNA/tree/master/doc/source

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

1 participant