[GRASS-git] [OSGeo/grass] f25cea: CI(docs): Generate Programmer's Manual with Doxyge...

[Edouard Choinière]

  Branch: refs/heads/main
  Home:   https://github.com/OSGeo/grass
  Commit: f25cea218f0a9cce6a50a637b3f444ce48767224
      https://github.com/OSGeo/grass/commit/f25cea218f0a9cce6a50a637b3f444ce48767224
  Author: Edouard Choinière <27212526+echoix at users.noreply.github.com>
  Date:   2025-07-21 (Mon, 21 Jul 2025)

  Changed paths:
    M .github/workflows/documentation.yml

  Log Message:
  -----------
  CI(docs): Generate Programmer's Manual with Doxygen in CI (#6092)

After having explored Doxygen a bit last week for potential improvements and upgrades, I asked Markus 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 https://github.com/OSGeo/grass/pull/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'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.
- Two generated search files not present anymore

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.


* CI(man): Generate Programmer's Manual with Doxygen in CI

* CI(docs): Add `--with-nls` configure flag

* CI(docs) Add gettext to dependencies in documentation workflow

* CI(docs): Enable postgres features for manual generation

* CI(docs): Set postgre include path

* CI(docs): Split configure and build of grass

* CI(docs): Make doxygen docs before building grass, as a compilation isn't needed

* CI(docs): Enable odbc features for doxygen manual generation

* CI(docs): Make doxygen docs artifact available as soon as finished

* CI(docs): Disable bzlib for doxygen docs to match existing published docs

* CI(docs): Upload doxygen html and latex artifacts separately

* CI(docs): Only run doxygen after build as lex/yacc files are generated during build

* CI(docs): Disable openmp for doxygen docs to match existing published docs

* CI(docs): Disable pthread for doxygen docs to match existing published docs

* CI(docs): Disable readline for doxygen docs to match existing published docs

* CI(docs): Exclude map and md5 files from doxygen artifact uploads



To unsubscribe from these emails, change your notification settings at https://github.com/OSGeo/grass/settings/notifications