docs: add documentation script - #514
Merged
Miou-zora merged 11 commits intoMar 26, 2026
Merged
Conversation
Copy link
Copy Markdown
Contributor
Sorry, something went wrong.
…ngs to configuration
Copy link
Copy Markdown
Contributor
|
Warning Rate limit exceeded@Miou-zora has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 12 minutes and 21 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR. We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 39cf0839-d4e5-4d91-9afb-8015be51096f 📥 CommitsReviewing files that changed from the base of the PR and between 3343f3d and 0afe1d8. 📒 Files selected for processing (1)
WalkthroughRefactors the documentation build to use xmake: adds a Doxygen config under docs/doxygen/, introduces an xmake build_documentation task that ensures the theme repo and invokes Doxygen, updates xmake includes, adjusts .gitignore for docs artifacts, and updates the GitHub Actions workflow to run xmake and publish docs/doxygen/output/html. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant GH as "GitHub Actions"
participant Repo as "Repository (checkout)"
participant XMake as "xmake (CI step)"
participant Theme as "doxygen-awesome-css (git)"
participant Doxy as "Doxygen binary"
participant Pages as "GitHub Pages publish"
GH->>Repo: checkout code
GH->>XMake: install xmake / cache
GH->>XMake: run `xmake build_documentation`
XMake->>Theme: check `docs/doxygen/doxygen-awesome-css`
alt theme missing
XMake->>Theme: git clone (branch v2.4.2)
else theme exists
XMake->>Theme: git pull (branch v2.4.2)
end
XMake->>Doxy: resolve installed doxygen binary
XMake->>Doxy: run doxygen with `docs/doxygen/Doxyfile.cfg`
Doxy-->>Repo: write HTML to `docs/doxygen/output/html`
GH->>Pages: publish `docs/doxygen/output/html`
Estimated Code Review Effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem🚥 Pre-merge checks | ✅ 3 ✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches 🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. ❤️ ShareComment @coderabbitai help to get the list of available commands and usage tips. |
Sorry, something went wrong.
Copy link
Copy Markdown
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agentsVerify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/workflows/deploy_doxygen_page.yml:
- Around line 31-36: The workflow’s push.paths filter is too narrow and omits
real inputs for the "Install Doxygen" and "Build documentation" steps, so update
the workflow's push.paths configuration to include the actual documentation and
source dependencies (e.g. docs/doxygen/Doxyfile.cfg,
tools/xmake/build_documentation.lua, src/**, examples/**, README.md) instead of
or in addition to the nonexistent root Doxyfile.cfg; ensure the workflow file
itself remains included so manual edits still trigger it, and remove the stale
root Doxyfile.cfg entry so documentation changes will automatically trigger the
job that runs the "Install Doxygen" and "Build documentation" steps.
In `@docs/doxygen/Doxyfile.cfg`:
- Around line 5-9: The INPUT multi-line assignment is broken because the second
line "examples/" is missing a continuation backslash; update the INPUT block so
the "examples/" entry ends with a trailing backslash, ensuring README.md is
included in INPUT and allowing USE_MDFILE_AS_MAINPAGE = README.md to work
correctly (look for the INPUT assignment and the
README.md/USE_MDFILE_AS_MAINPAGE settings).
In `@tools/xmake/build_documentation.lua`:
- Around line 9-11: The task currently calls project.required_package("doxygen")
(doxygen_package) and always fails because Doxygen was removed from project
add_requires; fix by either re-adding Doxygen to the project's add_requires (so
project.required_package("doxygen") can resolve the package using
doxygen_version) or change the logic in build_documentation.lua to detect
Doxygen outside project packages (e.g., check for a system-installed doxygen via
a tool-detection API or a tool-specific declaration) and fall back to that when
doxygen_package is nil; update the error/raise path accordingly to only raise if
neither a declared package nor a system/tool availability check succeeds.
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info ⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: aabd54d7-ced0-48fc-9ae9-20149b553517
📥 CommitsReviewing files that changed from the base of the PR and between 33c632b and 9b6c217.
📒 Files selected for processing (6)- .github/workflows/deploy_doxygen_page.yml
- .gitignore
- Doxyfile.cfg
- docs/doxygen/Doxyfile.cfg
- tools/xmake/build_documentation.lua
- xmake.lua
Sorry, something went wrong.
Comment thread
.github/workflows/deploy_doxygen_page.yml
Comment thread
docs/doxygen/Doxyfile.cfg
Comment thread
tools/xmake/build_documentation.lua
Outdated
Copy link
Copy Markdown
Contributor
|
✅ Actions performed
Review triggered.
|
Sorry, something went wrong.
Copy link
Copy Markdown
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)tools/xmake/build_documentation.lua (2)🤖 Prompt for all review comments with AI agents32-32: Use os.execv or quote paths to handle spaces safely.
String concatenation for shell commands can break if doxygen or the config path contains spaces. Using os.execv with an argument array is more robust.
♻️ Proposed fix🤖 Prompt for AI Agents- os.exec(doxygen .. " " .. path.join(os.projectdir(), "docs", "doxygen", "Doxyfile.cfg")) + os.execv(doxygen, {path.join(os.projectdir(), "docs", "doxygen", "Doxyfile.cfg")})Verify each finding against the current code and only fix it if needed. In `@tools/xmake/build_documentation.lua` at line 32, The current os.exec call builds a shell string that can break on spaces; change the os.exec invocation that calls doxygen (the line using os.exec(doxygen .. " " .. path.join(os.projectdir(), "docs", "doxygen", "Doxyfile.cfg"))) to a safe variant: either call os.execv with an argument table (use doxygen as the program and the config path returned from path.join as the single argument) or ensure both the doxygen variable and the path.join result are properly quoted/escaped before passing to os.exec so paths with spaces are handled correctly.
24-29: git.pull on a tag (v2.4.2) won't fetch updates.
Tags are immutable references. Calling git.pull with branch = "v2.4.2" when it's actually a tag won't pull any changes since tags don't advance. The else branch effectively does nothing useful.
Consider either:
♻️ Suggested simplification
- Simply skip the pull if the directory exists (tag content won't change)
- Or verify the correct tag is checked out and re-clone if it differs (for version upgrades)
🤖 Prompt for AI Agents- if not os.isdir(path.join(os.projectdir(), "docs", "doxygen", "doxygen-awesome-css")) then - print("Cloning doxygen-awesome-css repository...") - git.clone("https://github.com/jothepro/doxygen-awesome-css.git", { - branch = "v2.4.2", - outputdir = path.join(os.projectdir(), "docs", "doxygen", "doxygen-awesome-css") - }) - else - print("Updating doxygen-awesome-css repository...") - git.pull({ - repodir = path.join(os.projectdir(), "docs", "doxygen", "doxygen-awesome-css"), - branch = "v2.4.2" - }) - end + local theme_dir = path.join(os.projectdir(), "docs", "doxygen", "doxygen-awesome-css") + if not os.isdir(theme_dir) then + print("Cloning doxygen-awesome-css repository (tag v2.4.2)...") + git.clone("https://github.com/jothepro/doxygen-awesome-css.git", { + branch = "v2.4.2", + outputdir = theme_dir + }) + else + print("doxygen-awesome-css directory already exists, skipping clone.") + endVerify each finding against the current code and only fix it if needed. In `@tools/xmake/build_documentation.lua` around lines 24 - 29, The else branch currently calls git.pull({ repodir = path.join(os.projectdir(), "docs", "doxygen", "doxygen-awesome-css"), branch = "v2.4.2" }) but "v2.4.2" is a tag and git.pull on a tag does nothing; change the logic in the else branch to either (A) skip pulling when the directory exists (since tag content is immutable) or (B) validate the checked-out ref and, if it doesn't match the expected tag "v2.4.2", remove/reclone the repo and checkout the tag — implement this by checking the repo's current ref (using git commands or existing helpers) and using git.clone/git.checkout to ensure the tag is present rather than calling git.pull on a tag.
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@tools/xmake/build_documentation.lua`:
- Line 16: Replace the manual construction of the doxygen path (the local
variable `doxygen` built from `doxygen_package:installdir()` and "bin/doxygen")
with xmake's cross-platform program lookup by importing and calling
`find_program` from `lib.detect.find_program` (as used in
tools/xmake/format.lua) to locate the doxygen executable (handles `doxygen.exe`
on Windows); update the code that assigns `doxygen` so it calls
`find_program("doxygen")` (fall back to the package install dir only if
`find_program` returns nil) and ensure subsequent uses of the `doxygen` variable
remain unchanged.
---
Nitpick comments:
In `@tools/xmake/build_documentation.lua`:
- Line 32: The current os.exec call builds a shell string that can break on
spaces; change the os.exec invocation that calls doxygen (the line using
os.exec(doxygen .. " " .. path.join(os.projectdir(), "docs", "doxygen",
"Doxyfile.cfg"))) to a safe variant: either call os.execv with an argument table
(use doxygen as the program and the config path returned from path.join as the
single argument) or ensure both the doxygen variable and the path.join result
are properly quoted/escaped before passing to os.exec so paths with spaces are
handled correctly.
- Around line 24-29: The else branch currently calls git.pull({ repodir =
path.join(os.projectdir(), "docs", "doxygen", "doxygen-awesome-css"), branch =
"v2.4.2" }) but "v2.4.2" is a tag and git.pull on a tag does nothing; change the
logic in the else branch to either (A) skip pulling when the directory exists
(since tag content is immutable) or (B) validate the checked-out ref and, if it
doesn't match the expected tag "v2.4.2", remove/reclone the repo and checkout
the tag — implement this by checking the repo's current ref (using git commands
or existing helpers) and using git.clone/git.checkout to ensure the tag is
present rather than calling git.pull on a tag.
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info ⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: fb1a9d8e-62d1-4260-a369-fe45f2d93fca
📥 CommitsReviewing files that changed from the base of the PR and between 9b6c217 and 3343f3d.
📒 Files selected for processing (3)- .github/workflows/deploy_doxygen_page.yml
- docs/doxygen/Doxyfile.cfg
- tools/xmake/build_documentation.lua
- docs/doxygen/Doxyfile.cfg
Sorry, something went wrong.
Comment thread
tools/xmake/build_documentation.lua
| raise("Doxygen package not found. Please install it first. By running:\n\nxmake require -yvD \"doxygen " .. doxygen_version .. "\"") | ||
| end | ||
|
|
||
| local doxygen = path.join(doxygen_package:installdir(), "bin", "doxygen") |
Copy link
Copy Markdown
Contributor
There was a problem hiding this comment.
⚠️ Potential issue | 🔴 Critical
🧩 Analysis chain🏁 Script executed:
#!/bin/bash
# Check if xmake's doxygen package handles the extension automatically
rg -n "installdir.*bin.*doxygen" --type lua
# Also check if there are any platform-specific path constructions in the codebase
rg -n "is_plat.*windows" --type lua | head -20Repository: EngineSquared/EngineSquared
Length of output: 1264
🏁 Script executed:
#!/bin/bash
# Search for how other executables are called/built in lua files
rg -n "path\.join.*bin" --type lua -A 2 -B 2
# Also check if there's any .exe extension handling in the codebase
rg -n "\.exe" --type luaRepository: EngineSquared/EngineSquared
Length of output: 959
🏁 Script executed:
#!/bin/bash
# Check if there are any uses of os.exec or os.execv with special handling for windows
rg -n "os\.exec" --type lua -B 3 -A 1
# Look for any path handling with extensions
rg -n "path\." --type lua | grep -E "(extension|suffix|exe)" | head -10
# Check xmake documentation or comments about platform-specific exe handling
rg -n "windows.*exe|exe.*windows" --type luaRepository: EngineSquared/EngineSquared
Length of output: 1937
🏁 Script executed:
#!/bin/bash
# Let's look at the full build_documentation.lua file to understand the context better
cat -n tools/xmake/build_documentation.lua
# Also check what doxygen_package is and how it's obtained
rg -n "doxygen_package\|find_package" --type luaRepository: EngineSquared/EngineSquared
Length of output: 1972
🏁 Script executed:
#!/bin/bash
# Let's look at the format.lua to see how tools like clang-format are obtained and used
cat -n tools/xmake/format.lua
# Check if there are any comments or documentation about xmake's executable handling
rg -n "xmake.*windows|os\.exec" --type lua | head -30Repository: EngineSquared/EngineSquared
Length of output: 2736
🏁 Script executed:
#!/bin/bash
# Let's search for any documentation or examples of how xmake packages handle executables
# Check if there are similar patterns in the codebase with other packages
rg -n "package:installdir\(\)" --type lua -A 2 -B 2
# Also check if xmake has any utilities for finding executables within packages
rg -n "find_program\|find_file" --type lua -A 1 -B 1
# Search for any documentation comments about windows executable handling
rg -n "exe\|windows.*binary\|binary.*windows" --type luaRepository: EngineSquared/EngineSquared
Length of output: 460
🏁 Script executed:
#!/bin/bash
# Let's search for how xmake's os.exec handles executable extensions
# Check if there's any platform-specific code that handles exe on windows
rg -n "is_plat\(\"windows\"\)" tools/xmake/ -A 3
# Also check if there's any usage of os.addenv or similar for path construction
rg -n "addexe\|is_host\|target_os" --type lua
# Let's see how other build systems or projects handle this
# Check if there's a GitHub workflow that might shed light on how this is tested
git ls-files ".github/workflows/*.yml" 2>/dev/null | head -5Repository: EngineSquared/EngineSquared
Length of output: 214
🏁 Script executed:
#!/bin/bash
# Let's check the GitHub workflow that deploys doxygen to see how doxygen is called on windows
cat .github/workflows/deploy_doxygen_page.yml
# Also check the ci.yml to see if there are windows tests
cat .github/workflows/ci.ymlRepository: EngineSquared/EngineSquared
Length of output: 8313
🏁 Script executed:
#!/bin/bash
# Search for how other executables are handled in xmake Lua code
# Look specifically for patterns with .exe or executable handling
rg -n "os\.exec\|os\.execv" --type lua -B 3 -A 3 | head -50
# Check if there are any comments or patterns about cross-platform executable handling
rg -n "platform\|windows\|executable" tools/xmake/ --type lua
# Let's look for any find_program usages in build_documentation context
rg -n "find_program\|find_file" --type luaRepository: EngineSquared/EngineSquared
Length of output: 53
🏁 Script executed:
#!/bin/bash
# Let's search more carefully for os.exec patterns
rg "os\.exec" --type lua
# Search for any .exe mentions
rg "exe" --type lua
# Check xmake documentation patterns - see if there are any comments explaining the behavior
rg -n "exec\|execute" tools/xmake/ --type luaRepository: EngineSquared/EngineSquared
Length of output: 1213
🏁 Script executed:
#!/bin/bash
# Let's check if there's any xmake documentation in the repo about executable handling
find . -name "*.md" -type f | xargs grep -l "xmake\|executable\|windows" | head -10
# Check the README for any mentions of platform-specific issues
cat README.md 2>/dev/null | head -100
# Let's look more carefully at how find_program is imported and used
rg -n "find_program" --type lua -B 2 -A 5Repository: EngineSquared/EngineSquared
Length of output: 3111
Use xmake's find_program() to locate doxygen across platforms.
The current manual path construction at line 16 will fail on Windows where the executable is doxygen.exe. Instead of path.join(doxygen_package:installdir(), "bin", "doxygen"), use xmake's cross-platform executable discovery function as shown in tools/xmake/format.lua: import and call find_program() from lib.detect.find_program.
🤖 Prompt for AI AgentsVerify each finding against the current code and only fix it if needed.
In `@tools/xmake/build_documentation.lua` at line 16, Replace the manual
construction of the doxygen path (the local variable `doxygen` built from
`doxygen_package:installdir()` and "bin/doxygen") with xmake's cross-platform
program lookup by importing and calling `find_program` from
`lib.detect.find_program` (as used in tools/xmake/format.lua) to locate the
doxygen executable (handles `doxygen.exe` on Windows); update the code that
assigns `doxygen` so it calls `find_program("doxygen")` (fall back to the
package install dir only if `find_program` returns nil) and ensure subsequent
uses of the `doxygen` variable remain unchanged.
Sorry, something went wrong.
…h handling for Doxygen theme
Copy link
Copy Markdown
|
Sorry, something went wrong.
Miou-zora
added a commit
that referenced
this pull request
Mar 26, 2026
# Pull Request ## Description Add documentation generation script and update it in CI ## Related Issues (Put "None" if there are no related issues) None ## Type of Change Please delete options that are not relevant. - Documentation update - Build/CI configuration change ## Changes Made List the main changes in this PR: - Added the build_documentation script - Updated the CI to use it to build documentation - Updated the documentation inside the wiki (contributing part) ## Testing Describe the tests you ran to verify your changes. Please delete options that are not relevant. - Manual testing performed: launched `xmake build_documenation` ### Test Environment - OS: macOS - Compiler: Clang ## Screenshots/Videos (Put "None" if there are no related issues) None ## Documentation Please delete options that are not relevant. - No documentation changes are required ## Checklist (Don't delete any options) - [x] My code follows the style guidelines of this project - [x] I have performed a self-review of my own code - [x] I have commented my code, particularly in hard-to-understand areas - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] Any dependent changes have been merged and published ## Breaking Changes (Put "None" if there are no related issues) None ## Additional Notes (Put "None" if there are no related issues) None <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Chores** * CI workflow updated to trigger on main pushes and use the repository checkout v6. * Documentation build now runs via the project's build tool (xmake) and uses an integrated install step. * Published documentation output path changed to a nested docs/doxygen output directory. * Git ignore narrowed to only generated Doxygen artifacts. * **Documentation** * Added a centralized Doxygen configuration and theme integration for consistent API docs. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
Miou-zora
added a commit
that referenced
this pull request
Mar 27, 2026
Add documentation generation script and update it in CI None Please delete options that are not relevant. - Documentation update - Build/CI configuration change List the main changes in this PR: - Added the build_documentation script - Updated the CI to use it to build documentation - Updated the documentation inside the wiki (contributing part) Describe the tests you ran to verify your changes. Please delete options that are not relevant. - Manual testing performed: launched `xmake build_documenation` - OS: macOS - Compiler: Clang None Please delete options that are not relevant. - No documentation changes are required - [x] My code follows the style guidelines of this project - [x] I have performed a self-review of my own code - [x] I have commented my code, particularly in hard-to-understand areas - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] Any dependent changes have been merged and published None None <!-- This is an auto-generated comment: release notes by coderabbit.ai --> * **Chores** * CI workflow updated to trigger on main pushes and use the repository checkout v6. * Documentation build now runs via the project's build tool (xmake) and uses an integrated install step. * Published documentation output path changed to a nested docs/doxygen output directory. * Git ignore narrowed to only generated Doxygen artifacts. * **Documentation** * Added a centralized Doxygen configuration and theme integration for consistent API docs. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
7 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pull Request
Description
Add documentation generation script and update it in CI
Related Issues (Put "None" if there are no related issues)
None
Type of Change
Please delete options that are not relevant.
Changes Made
List the main changes in this PR:
Testing
Describe the tests you ran to verify your changes. Please delete options that are not relevant.
Test Environment
Screenshots/Videos (Put "None" if there are no related issues)
None
Documentation
Please delete options that are not relevant.
Checklist (Don't delete any options)
Breaking Changes (Put "None" if there are no related issues)
None
Additional Notes (Put "None" if there are no related issues)
None
Summary by CodeRabbit
Chores
Documentation