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

Doxygen update & cleanup #383

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Conversation

TeamCorgo
Copy link

This fork includes the following updates:

  • Removed old Doxygen files from the /doc folder.
  • Upgraded Doxygen from version 1.7.3 to 1.13.1 (latest stable version).
  • Added rescomp.txt to Doxygen for better user visibility.
  • Introduced a GitHub Action to automatically generate new documentation nightly.
  • Added a GitHub Action cleanup step to prevent the accumulation of deployments.

These changes aim to reduce bloat in the master branch, prevent documentation decay through automated generation, and enhance accessibility by hosting the documentation at: https://stephane-d.github.io/SGDK.

A live example is available here: https://teamcorgo.github.io/SGDK/.
*Ensure GitHub Pages is configured to use GitHub Actions as the source.

Copy link
Owner

@Stephane-D Stephane-D left a comment

Choose a reason for hiding this comment

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

Thanks a lot for your contribution ! I had a look on the new generated doxygen and it looks really great so far !
Historically I had the github.io pages enabled with some kind of documentation on it but a lot of people were just not aware it existed so I preferred to centralize everything on the SGDK repo directly. Also having the doc offline if definitely useful if you don't have access to internet for some reasons. Ideally it would be great to have a job to build up release archive containing a up to date doc folder and also publishing the doc on the wiki pages as well 👍

@TeamCorgo
Copy link
Author

Ok I am a bit stuck as Doxygen exports HTML and the Wiki uses Markdown so injecting the output of Doxygen into the wiki is not possible however it would be possible to migrate the Wiki into Doxygen.

Automating Doxygen Builds

GitHub Action to automate the generation of Doxygen documentation would:

  • Build the documentation upon each commit or pull request merge.
  • Save the generated results back into the repository, either: Within a dedicated branch for GitHub Pages (if we choose to host it there) or directly into a designated folder within the repository.
  • Identify that the update/change came from an automated process.

This ensures that Doxygen is always up to date as it no longer relies on human effort to maintain.

Consolidating Wiki into Doxygen Documentation

  • Doxygen generates HTML output, while the GitHub Wiki operates in Markdown. This creates a compatibility gap, requiring the Doxygen documentation to be hosted (either via GitHub Pages or a third-party service).
  • Once hosted, we can update the repository's README and the GitHub Wiki to link directly to the Doxygen documentation for visibility.

Since Doxygen supports Markdown, we could consider importing the existing GitHub Wiki content into Doxygen and consolidating all documentation (code, samples, and wiki content) within a single system.

  • Simplified maintenance: Reduces the need to manage multiple documentation sources.
  • Unified experience: Provides a single point of reference for developers, whether seasoned professionals or enthusiastic hobbyists.

Kill Doxygen from the project

The biggest issue is that the documentation is left to rot over time (this could pollute training for LLM's) and that wrong or misleading documentation could be more damaging than none. If Doxygen is killed from this repo another repo (1st or 3rd party) can be spun up to offer the automated documentation.

Let me know your preferred direction, and I’ll proceed accordingly and produce draft(s) for review.

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.

2 participants