Skip to content

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
merged 16 commits into from
Jul 21, 2025

Conversation

echoix
Copy link
Member

@echoix echoix commented Jul 20, 2025

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:

  • The bison/flex versions in CI is 3.8.2 instead of 3.7.5. The generated files for the sqlp SQL parser have some slight differences (like the source code copy).
  • The changes in gjson made during the last week, like m.measure: Add JSON support #6053, that changes some line numbers
  • The element order between uppercase and lowercase elements of the same string in the globals_*.html or globals_defs_*.html
  • The files excluded from uploading in the artifact, *.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).
  • Up to one pixel off plus slight different aliasing for most png graphs, due to a different compression, most probably different graphviz versions available on Ubuntu vs the Debian on the server.
  • The commit hash present in every page's title:
    • With the meld tool, I'm using the following regex to ignore these lines: 8\.5\.0dev\(2025\)-[0-9|a-f]{10}
  • The build date+time of each specific page, shown in the footer:
    • With the 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&#39;s Manual by \<
  • The html map's area tags that have slightly different coordinates, because of some images have a 1px size difference:
    • With the meld tool, I'm using the following regex to ignore these lines: ^\<area shape=\"rect\" (?:href=\"(?:.*)\" )?(?:title=\"(?:.*)\" )?alt=\"(?:.*)\" coords=\"\d*,\d*,\d*,\d*\"/\>
  • The _formula.log file that is not present: No latex output yet, and was judged not important by Markus to have being built. The log on the server fails anyways, as shown by the formulas not rendered in html too like for G_meridional_radius_of_curvature() https://grass.osgeo.org/programming8/defs_2gis_8h.html#aed5d22663e0f04be62e0426c0ce827c3. To solve later, after having the baseline merged in.
    • image
  • Two generated search files not present anymore

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.

@echoix echoix requested a review from wenzeslaus July 20, 2025 19:17
@github-actions github-actions bot added the CI Continuous integration label Jul 20, 2025
@echoix
Copy link
Member Author

echoix commented Jul 20, 2025

Also, in the mkdocs docs, there are some changes, especially in the db.columns, db.copy, db.login, etc tools, as new features were enabled in the builds (postgre and odbc), so new possible values are printed out in the docs.
There are also new grass-odbc.html, grass-pg.html, v.out.postgis.html pages created.
The topic, keyword, and sitemap, etc files updated with the new references.

image

@echoix
Copy link
Member Author

echoix commented Jul 20, 2025

I have two follow up PRs queued that depend on this.

@echoix echoix requested review from petrasovaa and removed request for wenzeslaus July 21, 2025 14:40
Copy link
Contributor

@petrasovaa petrasovaa left a 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 echoix merged commit f25cea2 into OSGeo:main Jul 21, 2025
29 checks passed
@github-actions github-actions bot added this to the 8.5.0 milestone Jul 21, 2025
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
Labels
CI Continuous integration
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants