diff --git a/CMakeLists.txt b/CMakeLists.txt index 98232c9258f..932ac1e04e3 100644 --- a/CMakeLists.txt +++ b/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} diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md index 5f20b381b51..706a2a5aa00 100644 --- a/REQUIREMENTS.md +++ b/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 diff --git a/include/Make/Install.make b/include/Make/Install.make index ba0147c61ea..86a29b89165 100644 --- a/include/Make/Install.make +++ b/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 diff --git a/man/CMakeLists.txt b/man/CMakeLists.txt index bc962806516..732a87082ba 100644 --- a/man/CMakeLists.txt +++ b/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=©$ 2003-${GRASS_VERSION_DATE} GRASS Development Team, GRASS ${GRASS_VERSION_NUMBER} Documentation" ) add_custom_target( diff --git a/man/Makefile b/man/Makefile index 36856be6117..13d6b1183fe 100644 --- a/man/Makefile +++ b/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="© 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="© 2003-$(GRASS_VERSION_DATE) GRASS Development Team, GRASS $(GRASS_VERSION_NUMBER) Documentation" \ mkdocs serve