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.

Sign up for GitHub

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

Jump to bottom

Multiple improvements to the documentation generation #159

Merged
merged 4 commits into from
Nov 7, 2024
Merged

Multiple improvements to the documentation generation #159

merged 4 commits into from
Nov 7, 2024

Commits on Nov 7, 2024

  1. doc: add dependency from the Doxygen target to the Doxygen config file 

    Add $BUILD/doc/Doxyfile (the Doxygen config file override created from
doc/Doxyfile.in) as a dependency of the Doxygen XML generation. This
change will ensure Doxygen is run again if its configuration has
changed.
    @qdeslandes
    qdeslandes committed Nov 7, 2024
    Configuration menu
    Copy the full SHA
    8b1010f View commit details
    Browse the repository at this point in the history

  2. doc: always build the doc without cache 

    Sphinx uses a cache to make the generation faster. However, if a change
is made to the source code documentation (e.g. in a comment), Sphinx
won't detect it and won't rebuild the documentation.

Prevent Sphinx from using its cache to prevent out-of-date
documentation.
    @qdeslandes
    qdeslandes committed Nov 7, 2024
    Configuration menu
    Copy the full SHA
    68861e5 View commit details
    Browse the repository at this point in the history

  3. doc: enable Doxygen autolink support 

    Breathe doesn't recognize Doxygen's `@ref` annotations, meaning every
`@ref` symbol is ignored and no hyperlink is created in the
documentation.

Instead, enable Doxygen's autolink feature so `symbol()` can be used to
link to a symbol in the documentation.
    @qdeslandes
    qdeslandes committed Nov 7, 2024
    Configuration menu
    Copy the full SHA
    54e28fc View commit details
    Browse the repository at this point in the history

  4. doc: clarify how Doxygen comments should be written 

    Modify the Doxygen comments guidelines to ensure references to functions
are properly processed by Breathe: use ` (backticks) instead of @ref or
@c and end functions with parentheses.
    @qdeslandes
    qdeslandes committed Nov 7, 2024
    Configuration menu
    Copy the full SHA
    bdae6fe View commit details
    Browse the repository at this point in the history