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 support for Mermaid charts to Doxygen #1006

Merged
merged 4 commits into from
Nov 25, 2024
Merged

Add support for Mermaid charts to Doxygen #1006

merged 4 commits into from
Nov 25, 2024

Conversation

azrogers
Copy link
Contributor

@azrogers azrogers commented Nov 21, 2024

As per #997, this PR adds support for Mermaid charts in Doxygen. It allows Mermaid charts to be added to the doc/diagrams folder and included in comments using the @mermaid{filename} alias. You can test it out by grabbing some Mermaid code, for example from this bit of their documentation, putting it in doc/diagrams/test.mmd, and adding a @mermaid{test} command to any Doxygen comment. After generating the docs, you should see the chart show up where the command was placed.

I've put this into a draft PR for the moment because somehow these changes have resulted in the sidebar disappearing. I believe this is a result of modifying Doxygen's footer.html, but I can't tell exactly why it would have this effect. Needs to be fiddled with.

Fixes #997

@azrogers azrogers marked this pull request as ready for review November 21, 2024 21:49
@azrogers
Copy link
Contributor Author

For whatever reason, looks like reordering the footer.html and Doxygen settings made the treeview show up again. Black magic.

@azrogers
Copy link
Contributor Author

For reference, the icon pack I chose here is Mingcute, chosen because it's Apache licensed, meaning we can use it without attribution, and it has a good mix of having a lot of icons to choose from, and not being as big as some (the material-symbols icon set is almost 7MB!). If anyone has any preferences for other icon sets to choose, there's no reason we can't swap them out.

@kring
Copy link
Member

kring commented Nov 25, 2024

I made a couple of small changes...

  1. CMakeLists.txt was clobbering the previous value of DOXYGEN_EXAMPLE_PATH, which broke code samples added with @snippet. I just made it append the diagrams path instead.
  2. The icons didn't work when the docs were loaded from a file:/// URL, because browser cross-origin rules forbid fetching file from the local file system with fetch. I fixed this with an old school trick: renamed the .json to .json.js and loaded it via a script tag instead.

Otherwise, looks great, merging!

@kring kring merged commit 91682ca into main Nov 25, 2024
20 checks passed
@kring kring deleted the mermaid branch November 25, 2024 06:48
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.

Include Mermaid diagrams in Doxygen
2 participants