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

Add initial xrefsect support #589

Merged
merged 2 commits into from
Oct 20, 2020
Merged

Add initial xrefsect support #589

merged 2 commits into from
Oct 20, 2020

Conversation

utzig
Copy link
Contributor

@utzig utzig commented Oct 9, 2020

Add basic parsing support and rendering of xrefsect blocks. The current implementation does not generate links or any pages.

An xrefsect is generated when a @xrefitem keyword is found in Doxygen documentation, as well as the specialized forms like \bug, \test and \deprecated.

https://www.doxygen.nl/manual/commands.html#cmdxrefitem

Add basic parsing support and rendering of xrefsect blocks. The current
implementation does not generate links or any pages.

An xrefsect is generated when a @xrefitem keyword is found in Doxygen
documentation, as well as the specialized forms like @bug, @test and
@deprecated.

https://www.doxygen.nl/manual/commands.html#cmdxrefitem

Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
@utzig
Copy link
Contributor Author

utzig commented Oct 9, 2020

For an example, this source:

/**
 * This is just some non-useful text.
 *
 * @xrefitem examples "Examples" "Examples" "Some xrefitem example"
 *
 * @bug Super buggy function
 */
void some_xref_fn(void);

/**
 * More non-useful text.
 *
 * @xrefitem examples "Examples" "Examples" "Some xrefitem example"
 *
 * @deprecated Don't use this
 */
void another_xref_fn(void);

Will render like this:

xrefitem

@vermeeren vermeeren self-requested a review October 9, 2020 14:56
@vermeeren vermeeren self-assigned this Oct 9, 2020
@vermeeren vermeeren added code Source code enhancement Improvements, additions (also cosmetics) labels Oct 9, 2020
Copy link
Collaborator

@vermeeren vermeeren left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@utzig Diff itself is good, but could you add the documentation example to the doc? I'm thinking somewhere on documentation/source/specific.rst is good. Probably with a title like Doxygen xrefsect. Thanks!

Add new section with xrefsect examples to specific page; add a \todo,
\test, \deprecated and \bug Doxygen special commands and create a
custom aliased xrefitem.

Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
@utzig
Copy link
Contributor Author

utzig commented Oct 19, 2020

@utzig Diff itself is good, but could you add the documentation example to the doc? I'm thinking somewhere on documentation/source/specific.rst is good. Probably with a title like Doxygen xrefsect. Thanks!

Done.

Copy link
Collaborator

@vermeeren vermeeren left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@utzig Thanks, much appreciated!

@vermeeren vermeeren merged commit 0bc9ba7 into breathe-doc:master Oct 20, 2020
@utzig utzig deleted the xrefsect branch October 20, 2020 15:18
vermeeren added a commit that referenced this pull request Oct 20, 2020
@vermeeren
Copy link
Collaborator

@utzig Released as v4.23.0.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
code Source code enhancement Improvements, additions (also cosmetics)
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants