docs: Ship the MkDocs documentation site with the installation

CMakeLists.txt

@@ -373,6 +373,36 @@ if(WITH_DOCS)
         DIRECTORY ${OUTDIR}/${GRASS_INSTALL_DOCDIR}/
         DESTINATION ${GRASS_INSTALL_DOCDIR}
     )
+    # The documentation site ships with the installation: build it at install
+    # time so the default build does not need mkdocs. When mkdocs is not
+    # available (e.g. it is in a user environment but the install runs under
+    # sudo), a site built earlier by the build-mkdocs target is still
+    # installed; otherwise the site is skipped with a warning and the help
+    # system uses its fallbacks.
+    if(NOT WITH_FHS)
+        install(
+            CODE
+                "
+            find_program(MKDOCS_EXECUTABLE mkdocs)
+            if(MKDOCS_EXECUTABLE)
+                message(STATUS \"Building the MkDocs documentation site\")
+                set(ENV{SITE_NAME} \"GRASS ${GRASS_VERSION_MAJOR}.${GRASS_VERSION_MINOR} Documentation\")
+                set(ENV{COPYRIGHT} \"© 2003-${GRASS_VERSION_DATE} GRASS Development Team, GRASS ${GRASS_VERSION_NUMBER} Documentation\")
+                execute_process(
+                    COMMAND \${MKDOCS_EXECUTABLE} build
+                    WORKING_DIRECTORY ${OUTDIR}/${GRASS_INSTALL_MKDOCSDIR}
+                    RESULT_VARIABLE mkdocs_status)
+                if(NOT mkdocs_status EQUAL 0)
+                    message(WARNING \"mkdocs build failed; the documentation site will be incomplete or missing\")
+                endif()
+            elseif(EXISTS \"${OUTDIR}/${GRASS_INSTALL_MKDOCSDIR}/site\")
+                message(STATUS \"mkdocs not found; installing the previously built documentation site\")
+            else()
+                message(WARNING \"mkdocs not found, the documentation site will not be installed. To include it, install the Python packages listed in man/mkdocs/requirements.txt and run cmake --install again.\")
+            endif()
+            "
+        )
+    endif()
     install(
         DIRECTORY ${OUTDIR}/${GRASS_INSTALL_MKDOCSDIR}/
         DESTINATION ${GRASS_INSTALL_MKDOCSDIR}

REQUIREMENTS.md

@@ -36,8 +36,10 @@ for other platforms you may have to install some of them.
   GDAL: [https://gdal.org](https://gdal.org)
 - **Python >= 3.11** (for temporal framework, scripts, wxGUI, and ctypes interface)
   [https://www.python.org](https://www.python.org)
-- **MkDocs** with "Material" theme Python packages for the manual pages:
-  See `man/mkdocs/requirements.txt`.
+- **MkDocs** with "Material" theme Python packages for the documentation
+  site installed with GRASS: See `man/mkdocs/requirements.txt`. When MkDocs
+  is not available at install time, the installation proceeds without the
+  documentation site.
 
 ## Optional packages
 

include/Make/Install.make

@@ -33,6 +33,7 @@ strip-check:
 install:
 	@ echo $(ARCH_BINDIR)/$(GRASS_NAME)
 	$(MAKE) install-check-built
+	$(MAKE) build-mkdocs
 ifeq ($(strip $(MACOSX_APP)),1)
 	$(MAKE) install-macosx
 else
@@ -49,6 +50,23 @@ install-check-built:
 		exit; \
 	fi
 
+# The documentation site ships with the installation: build it into the dist
+# tree so the install copy includes it. When mkdocs is not available (e.g.
+# it is in a user environment but the install runs under sudo), a site built
+# earlier by "make -C man build-mkdocs" is still installed; otherwise the
+# site is skipped with a warning and the help system uses its fallbacks.
+build-mkdocs:
+	@ if command -v mkdocs >/dev/null 2>&1 ; then \
+		$(MAKE) -C man build-mkdocs || \
+		echo "WARNING: mkdocs build failed, the documentation site will be incomplete or missing." >&2 ; \
+	elif [ -d "$(MDDIR)/site" ] ; then \
+		echo "mkdocs not found; using the previously built documentation site." ; \
+	else \
+		echo "WARNING: mkdocs not found, the documentation site will not be" >&2 ; \
+		echo "  installed. To include it, install the Python packages listed" >&2 ; \
+		echo "  in man/mkdocs/requirements.txt and run make install again." >&2 ; \
+	fi
+
 install-check-parent: | $(DESTDIR)
 	@ INST_PATH=`dirname $(DESTDIR)$(INST_DIR)`; \
 	while [ ! -d "$(DESTDIR)$$INST_PATH" ]; do \
@@ -187,6 +205,7 @@ install-strip:
 	$(MAKE) install
 
 bindist:
+	$(MAKE) build-mkdocs
 ifeq ($(strip $(MACOSX_APP)),1)
 	$(MAKE) bindist-macosx
 else
@@ -254,5 +273,5 @@ srclibsdist: distclean
 
 .PHONY: strip strip-check
 .PHONY: install-check-built install-check-parent install-check-writable install-check-prefix
-.PHONY: install real-install install-strip install-macosx
+.PHONY: install real-install install-strip install-macosx build-mkdocs
 .PHONY: bindist real-bindist bindist-macosx srcdist srclibsdist

man/CMakeLists.txt

@@ -226,7 +226,7 @@ if(NOT WITH_FHS)
         ${CMAKE_COMMAND}
         -E
         env
-        "SITE_NAME=GRASS ${GRASS_VERSION_NUMBER} Documentation"
+        "SITE_NAME=GRASS ${GRASS_VERSION_MAJOR}.${GRASS_VERSION_MINOR} Documentation"
         "COPYRIGHT=&copy$<SEMICOLON> 2003-${GRASS_VERSION_DATE} GRASS Development Team, GRASS ${GRASS_VERSION_NUMBER} Documentation"
     )
     add_custom_target(

man/Makefile

@@ -310,11 +310,11 @@ $(MDDIR)/overrides/fragments/tags/default/listing.html: mkdocs/overrides/fragmen
 	$(INSTALL_DATA) $< $@
 
 build-mkdocs:
-	@cd $(MDDIR) ; SITE_NAME="GRASS $(GRASS_VERSION_NUMBER) Documentation" \
+	@cd $(MDDIR) ; SITE_NAME="GRASS $(GRASS_VERSION_MAJOR).$(GRASS_VERSION_MINOR) Documentation" \
 	COPYRIGHT="&copy; 2003-$(GRASS_VERSION_DATE) GRASS Development Team, GRASS $(GRASS_VERSION_NUMBER) Documentation" \
 	mkdocs build
 
 serve-mkdocs:
-	@cd $(MDDIR) ; SITE_NAME="GRASS $(GRASS_VERSION_NUMBER) Documentation" \
+	@cd $(MDDIR) ; SITE_NAME="GRASS $(GRASS_VERSION_MAJOR).$(GRASS_VERSION_MINOR) Documentation" \
 	COPYRIGHT="&copy; 2003-$(GRASS_VERSION_DATE) GRASS Development Team, GRASS $(GRASS_VERSION_NUMBER) Documentation" \
 	mkdocs serve