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

treewide: Add Doxygen-generated docs #189

Merged
merged 5 commits into from
Aug 28, 2024
Merged

treewide: Add Doxygen-generated docs #189

merged 5 commits into from
Aug 28, 2024

Conversation

colluca
Copy link
Collaborator

@colluca colluca commented Aug 28, 2024

The existing snRuntime docs setup uses Doxygen to document the C sources, and then converts the generated XML code to Markdown for inclusion in our MkDocs documentation. The tool used for the conversion is no longer maintained. I searched and tried some alternatives (moxygen, mkdoxy) but they didn’t seem robust enough. The best approach would be to use Sphinx+breathe, but our doc engine is MkDocs and shifting to Sphinx would probably require more work.

This PR implements the following contributions:

  • To ease maintenance, drop the conversion from Doxygen XML docs to Markdown altogether, and just include the Doxygen-generated HTML pages on our site. Unfortunately, the style is not consistent with the other docs, but this is less relevant.
  • Add docstrings for the team, alloc_v2, sync, dma and ssr modules of the snRuntime, containing the minimum set of functions a user would need to implement optimized code for Snitch.
  • Install Doxygen on the Docker container, and run the CI job deploying the docs within the container.
  • Test Doxygen doc build on every branch, not only when deploying on main (cause for the CI failure on main).

@colluca colluca marked this pull request as ready for review August 28, 2024 12:13
@colluca colluca marked this pull request as draft August 28, 2024 13:06
@colluca colluca marked this pull request as ready for review August 28, 2024 14:06
@colluca colluca merged commit d024b04 into main Aug 28, 2024
25 of 27 checks passed
@colluca colluca deleted the doxygen-docs branch August 28, 2024 14:08
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.

1 participant