-
-
Notifications
You must be signed in to change notification settings - Fork 362
CI(docs): Generate Programmer's Manual with Doxygen in CI #6092
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
Merged
+59
−2
Conversation
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
I have two follow up PRs queued that depend on this. |
petrasovaa
approved these changes
Jul 21, 2025
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good to me!
echoix
added a commit
that referenced
this pull request
Jul 24, 2025
… tags (#6097) Similar to the bunch of fixes I did with sphinx in the last months or so, here is a first PR solving Doxygen warnings that can now be seen in CI (since #6092). It is a first batch with what I have yet, no particular grouping expect at the commit level. - Make doxygen ignore CMake build folders when looking for source documents, like in #5191 and #5208 - Fix wrong parameter names in docstrings - Add non documented parameters to the docstrings - Feel free to suggest some content when they didn’t exist yet, I went the easiest way that wasn’t creating something misleading. So when I didn’t know, I didn’t describe it at all. - fix syntax, and escape some characters when complaining - A small number of files I had to reflow the docstrings to be readable again, as it was joined together probably by a clang-format once. So these have a bigger diff. There’s still lots of the same categories, it’s only what I had done yet. * docs(lib): Update parameter descriptions for to match function signature * docs(lib): Fix formatting of parameter descriptions to solve doxygen warnings * man: Ignore cmake folders in doxygen config file * docs(lib): Update parameter descriptions to match function signature * lib/display/tran_colr: Fill docs for D_color_number_to_RGB according to signature * lib/display/raster2 Update parameter descriptions to match function signature * include: Update file paths in header comments to include 'grass' directory * docs: Escape `@`, `<` or `>` in doxygen docstrings * docs: Add missing param tags in doxygen docstrings * docs: Rename param tags to match signature in doxygen docstrings * docs: Escape `/*` to avoid nested comment warning in grasslib.dox * docs: Fix misformed `<b>` tag in doxygen docstrings of lib/gmath/fft.c * docs(lib): Fix formatting of parameter descriptions to solve doxygen warnings * docs: Document parameters and returns in doxygen docstrings * docs(lib): Fix formatting of lz4.h * docs: Fix typo in file name of lib/imagery/manage_signatures.c header * docs: Add missing param tags in doxygen docstrings * docs: Rename param tags to match signature in doxygen docstrings * docs(lib): Fix formatting of parameter descriptions to solve doxygen warnings * Apply suggestions from code review Co-authored-by: Anna Petrasova <[email protected]> * Apply suggestions from code review --------- Co-authored-by: Anna Petrasova <[email protected]>
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.
After having explored Doxygen a bit last week for potential improvements and upgrades, I asked @neteler last week to send me a snapshot of the doxygen-generated docs that are set up and published on the server. I wanted to have a true baseline of what the documentation workflow on the server was doing, in order to safely compare any improvements, such as upgrading the doxygen version to benefit from the numerous improvements in the past years, which aren't available in a distro's repos, especially an LTS version.
This PR does exactly this: Builds the doxygen docs in CI (previously never built in CI), and uploads an artifact that can be inspected and compared. The configure flags were changed to disable features with
--with-FEATURE=no
instead of--without-FEATURE
or removing the line if not enabled by default. This is because these will be enabled back after this initial PR, but to keep the differences small with what is published on the server and what is built in CI with this PR.The known and understood remaining differences with the snapshot of Monday Jul 14 2025:
globals_*.html
orglobals_defs_*.html
*.map
and*.md5
, of the same base name of each image file made by DOT, as they are only used to avoid regenerating them, which isn't applicable in CI where a fresh copy is made (we wouldn't need to publish them anyways).meld
tool, I'm using the following regex to ignore these lines:8\.5\.0dev\(2025\)-[0-9|a-f]{10}
meld
tool, I'm using the following regex to ignore these lines:\<li class="footer"\>Generated on \w\w\w \w\w\w \d\d? \d\d\d\d \d\d:\d\d:\d\d for GRASS GIS 8 Programmer's Manual by \<
meld
tool, I'm using the following regex to ignore these lines:^\<area shape=\"rect\" (?:href=\"(?:.*)\" )?(?:title=\"(?:.*)\" )?alt=\"(?:.*)\" coords=\"\d*,\d*,\d*,\d*\"/\>
The snapshot of the server cannot be uploaded here, as it is more than 25 MB (103 MB).
Once merged, the programmer's manual could be updated from the artifacts like the mkdocs site, as some upcoming changes probably won't be supported by the outdated Doxygen version previously used. Anyways, these programming docs should be distributed already built, and is not something that users need to build for compiling grass. There's way more benefits to having the best docs possible, instead of having every possible platform and setup being able to recreate our Doxygen docs website.