[petrasovaa]

Part of the transition to markdown-based documentation.

TL;DR:
make install/make bindist and cmake --install now build and ship the MkDocs documentation site, which g.manual and the GUI then use; if mkdocs is missing, the site is skipped with a warning and nothing else changes.

---

Ship the MkDocs documentation site with the installation. g.manual and the GUI help viewer already prefer $GISBASE/docs/mkdocs/site` when it exists, so installs pick it up automatically; the legacy HTML pages remain as fallback until a later phase removes them.

The site is built at install time rather than in the default build, so mkdocs (man/mkdocs/requirements.txt) does not become a build dependency and CI is unaffected:

• Autotools: make install and make bindist build the site into the dist tree via a new top-level build-mkdocs target; the install copy then includes it.
• CMake: an install(CODE) step runs mkdocs build during cmake --install.

When mkdocs is not on PATH at install time (e.g. it is in a user environment but the install runs under sudo), a site built beforehand (make -C man build-mkdocs or the build-mkdocs CMake target) is still installed; without one, the site is skipped with a warning. A failed build likewise warns instead of aborting the install.

Also align the local targets' SITE_NAME with the site published by the documentation workflow: the title is now
GRASS <major>.<minor> Documentation everywhere, while the exact version (including dev) stays in the copyright footer.

Note for packagers: the site adds roughly 120-200 MB, temporarily double accounting next to the legacy HTML pages until those are removed.

Implemented with AI assistance (Claude Fable).

[ninsbl]

Looks good to me.

[echoix]

That looks weird to me, to have the code as string, but that's probably in order to not parse it when it would error out.

Packagers will probably have to patch this if they split out docs to another package.

Do we know the extra time it takes at install time?

[echoix]

And are we actually going through that code path in CI somewhere?

[echoix]

And are we actually going through that code path in CI somewhere?

AI:
documentation.yml:149 runs make install before its "Get mkdocs" step (documentation.yml:227-229), so it too hits the warning branch, then pip-installs mkdocs and runs mkdocs build by hand at line 239. So CI covers mkdocs build itself, but not the new install glue.

Details

Reviewed PR #7747 (docs: Ship the MkDocs documentation site with the installation, petrasovaa:ship-mkdocs-installation) — 5 files, ~60 added lines.

Answers to your two review comments (not posted)

"Are we actually going through that code path in CI somewhere?" — Only the failure/fallback branch, never the success branch. No CI job has mkdocs on PATH at install time:

• cmake.yml:87 (cmake --install) installs no Python packages at all → hits the final else() "mkdocs not found" warning.
• build_ubuntu-{22,24}.04[_without_x].sh and macos_install.sh (make install) → same warning branch.
• documentation.yml:149 runs make install before its "Get mkdocs" step (documentation.yml:227-229), so it too hits the warning branch, then pip-installs mkdocs and runs mkdocs build by hand at line 239. So CI covers mkdocs build itself, but not the new install glue.
• Dockerfiles (docker/*/Dockerfile, root Dockerfile) → no mkdocs either.
• osgeo4w.yml never runs make install (only make), and make bindist is not run by any workflow — that new build-mkdocs call is entirely untested.

To actually cover it, the cheapest option is pip install -r man/mkdocs/requirements.txt before the install step in one job (cmake.yml is the natural one, it is already the only cmake --install coverage).

"Do we know the extra time it takes at install time?" — From the latest successful Documentation run on main (run 33915975818, 2026-09-04), the "Run mkdocs" step took 88 s on a 4-core GitHub runner, and that covers core plus addons docs with the social-card plugin enabled; core-only will be somewhat less, so roughly a minute added to every make install / cmake --install. For size, that run's mkdocs-site artifact is 170 MB compressed (includes addons and the Sphinx libpython tree), consistent with the 120-200 MB estimate in the PR description. Also worth noting the cost is paid on every install — mkdocs has no incremental build and the code never skips an up-to-date site.

Findings

• include/Make/Install.make:60 — A failed/interrupted mkdocs build only warns, but mkdocs clears site_dir before failing, so an empty/partial docs/mkdocs/site still gets installed; scripts/g.manual/g.manual.py:79 and gui/wxpython/gui_core/ghelp.py:759 branch on that directory's existence alone, so g.manual fatals "No HTML manual page entry" for every tool instead of using the intact docs/html fallback. The failure branch should delete site/.
• CMakeLists.txt:395 — Same defect on the CMake side: message(WARNING) then the following install(DIRECTORY ...MKDOCSDIR/) ships the partial site.
• include/Make/Install.make:36 — build-mkdocs runs before install-check-parent/writable/prefix, so a non-root make install to /usr/local renders the whole site (~90 s) and only then aborts with "install directory is not writable".
• include/Make/Install.make:59 — Docs are built into the build tree, not DESTDIR; with a system-packaged mkdocs on PATH, sudo make install leaves root-owned files in the user's dist.$ARCH/docs/mkdocs/site, breaking later unprivileged make/make clean. Contradicts the comment's assumption that mkdocs is simply not found under sudo. (CMake install(CODE) has the same property.)
• CMakeLists.txt:382 — Unconditional re-render on every cmake --install, and CPack runs the same install script, so packaging pays it repeatedly.
• CMakeLists.txt:383 — CI coverage gap as described above.

No bugs found in the SITE_NAME change itself: GRASS_VERSION_MAJOR/MINOR are defined in both include/Make/Grass.make and the top-level CMake scope, docs is already in BIN_DIST_FILES so bindist ships the site, the new build-mkdocs make target does not collide (only the top-level Makefile includes Install.make), and the CMake install(CODE) escaping/ordering (\${MKDOCS_EXECUTABLE} at install time, configure-time ${OUTDIR}, WORKING_DIRECTORY matching mkdocs_dir from man/CMakeLists.txt:130) is correct; a non-numeric RESULT_VARIABLE from a bad working directory also correctly lands in the warning branch.