Skip to content

Add Doxygen documentation infrastructure#8

Merged
glopesdev merged 7 commits intomainfrom
docs-dev
Jun 28, 2025
Merged

Add Doxygen documentation infrastructure#8
glopesdev merged 7 commits intomainfrom
docs-dev

Conversation

@glopesdev
Copy link
Contributor

@glopesdev glopesdev commented Jun 14, 2025

  • Doxygen version 1.12.0 and the Doxygen Awesome CSS theme were used.
  • Root favicon and logo added for consistency with other Harp documentation websites.
  • Triple slash added to existing function documentation comments so it gets automatically picked up by Doxygen.
  • OPTIMIZE_OUTPUT_FOR_C flag was set to adjust generated docs terminology.

Following merge to main the new layout will be published.


Documentation will automatically publish to GitHub Pages when:

  • A release is made
  • A manual workflow dispatch is initiated and publishing is enabled
  • Any push to any branch is made when CONTINUOUS_DOCUMENTATION is enabled (intended for use in forks for development purposes, but this is not enforced.)

Preview at: https://glopesdev.github.io/core.atxmega/

Moved the .gitignore file to the root of the repository to facilitate
central editing.
This is to ensure Doxygen can pick up these descriptions into generated
documentation.
@glopesdev glopesdev added the documentation Improvements or additions to documentation label Jun 14, 2025
@PathogenDavid
Copy link

For the benefit of anyone else who happens to notice that the globals index on the ATxmega core isn't super great compared to the same page in the Pico core:

Doxygen has a hard-coded cutoff where it splits those indices across multiple files and it's absurdly low at just 200 members. (This limit was set back in 2005 when dinosaurs still roamed the earth.)

Also worth noting that ALPHABETICAL_INDEX is completely unrelated to these pages. That corresponds to this index instead. (Quite annoyingly, this file doesn't seem to have a limit and even intelligently puts _ at the end.)

There's actually an issue and corresponding PR to improve this, but both seem to have stalled out. (To my dismay the PR unfortunately also doesn't let you disable the feature entirely and caps the maximum at 3,000.)

Copy link

@PathogenDavid PathogenDavid left a comment

Choose a reason for hiding this comment

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

Everything I mentioned in harp-tech/core.pico#56 (review) also applies to this PR.

@glopesdev glopesdev merged commit 78decbe into main Jun 28, 2025
5 checks passed
@glopesdev glopesdev deleted the docs-dev branch June 28, 2025 10:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants