From: Karl Fleischmann <karl.fleischmann@open-xchange.com>
Date: Wed, 13 Apr 2022 10:24:55 +0000 (+0200)
Subject: m4: Use documentation project in build pipeline
X-Git-Tag: 2.4.0~4066
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=223f747eee97e5bcb4ffbfde90d10287436a217f;p=thirdparty%2Fdovecot%2Fcore.git

m4: Use documentation project in build pipeline

To replace the wiki as the main documentation in the distribution
package the documentation project needs to be pulled into this project
in a build step. This commit checks the environment (e.g. python/venv)
and downloads/builds the documentation for packaging.
---

diff --git a/.gitignore b/.gitignore
index 6d14ec68fe..be1d3d11b3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -62,6 +62,10 @@ src/**/test-*
 !src/**/test-*.h
 !src/**/test-*.inc
 
+doc/venv
+doc/documentation*
+doc/html
+
 doc/man/doveadm-acl.1
 doc/man/doveadm-altmove.1
 doc/man/doveadm-auth.1
diff --git a/configure.ac b/configure.ac
index f61b204c18..ffb4a50df4 100644
--- a/configure.ac
+++ b/configure.ac
@@ -243,6 +243,8 @@ DOVECOT_WANT_SYSTEMD
 dovecot_moduledir="$libdir/dovecot"
 DC_DOVECOT_MODULEDIR
 
+DOVECOT_CHECK_PYTHON_VENV
+
 AC_ARG_WITH(docs,
 AS_HELP_STRING([--with-docs], [Install documentation (default)]),
 	if test x$withval = xno; then
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 4db1b86af3..2b939b37e2 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,8 +1,7 @@
-if INSTALL_DOCS
-DOCDIRS = wiki example-config
-endif
+extra_dist_extra =
 
-SUBDIRS = man $(DOCDIRS)
+SUBDIRS = man example-config
+DOCDIRS = wiki example-config
 
 docfiles = \
 	documentation.txt \
@@ -15,9 +14,59 @@ docfiles = \
 	solr-config-7.7.0.xml
 
 if INSTALL_DOCS
+if HAVE_VENV
+extra_dist_extra += html
+documentation_sources = documentation-main
+
+# extracting the documentation tarball from github yields the
+# "documentation-main" directory
+$(documentation_sources)/requirements.txt:
+	$(AM_V_GEN)wget -O - \
+		https://github.com/dovecot/documentation/archive/refs/heads/main.tar.gz | \
+	  tar xz
+
+venv: $(documentation_sources)/requirements.txt
+	$(AM_V_GEN)$(PYTHON) -m venv venv && \
+		venv/bin/pip install -r $<
+
+html: venv
+	$(AM_V_GEN)venv/bin/python -msphinx -b html $(documentation_sources)/source html
+
+else # if HAVE_VENV
+
+html:
+	if [ ! -e html/index.html ]; then echo "Building html documentation needs python installed"; fi
+
+endif # if HAVE_VENV
+
+# hack to build pages only if they're missing
+all-hook: html
+	if [ ! -e html/index.html ]; then $(MAKE) html; fi
+
+# explicit hook for make dist
+dist-hook: html
+
+install-data-local:
+	if [ ! -e html/index.html ]; then $(MAKE) html; fi
+	cp -nrf html "$(DESTDIR)$(docdir)"
+
+uninstall-local:
+	-rm -rf "$(DESTDIR)$(docdir)/html"
+
+clean-local:
+	-rm -rf venv
+	-rm -rf $(documentation_sources)
+
+distclean-local: clean-local
+	-rm -rf html
+
+maintainer-clean: distclean-local
+
+endif # if INSTALL_DOCS
+
 doc_DATA = $(docfiles)
-endif
 
 EXTRA_DIST = \
 	dovecot-initd.sh \
+	$(extra_dist_extra) \
 	$(docfiles)
diff --git a/m4/ax_python_module.m4 b/m4/ax_python_module.m4
new file mode 100644
index 0000000000..f0f873d199
--- /dev/null
+++ b/m4/ax_python_module.m4
@@ -0,0 +1,56 @@
+# ===========================================================================
+#     https://www.gnu.org/software/autoconf-archive/ax_python_module.html
+# ===========================================================================
+#
+# SYNOPSIS
+#
+#   AX_PYTHON_MODULE(modname[, fatal, python])
+#
+# DESCRIPTION
+#
+#   Checks for Python module.
+#
+#   If fatal is non-empty then absence of a module will trigger an error.
+#   The third parameter can either be "python" for Python 2 or "python3" for
+#   Python 3; defaults to Python 3.
+#
+# LICENSE
+#
+#   Copyright (c) 2008 Andrew Collier
+#
+#   Copying and distribution of this file, with or without modification, are
+#   permitted in any medium without royalty provided the copyright notice
+#   and this notice are preserved. This file is offered as-is, without any
+#   warranty.
+
+#serial 9
+
+AU_ALIAS([AC_PYTHON_MODULE], [AX_PYTHON_MODULE])
+AC_DEFUN([AX_PYTHON_MODULE],[
+    if test -z $PYTHON;
+    then
+        if test -z "$3";
+        then
+            PYTHON="python3"
+        else
+            PYTHON="$3"
+        fi
+    fi
+    PYTHON_NAME=`basename $PYTHON`
+    AC_MSG_CHECKING($PYTHON_NAME module: $1)
+    $PYTHON -c "import $1" 2>/dev/null
+    if test $? -eq 0;
+    then
+        AC_MSG_RESULT(yes)
+        eval AS_TR_CPP(HAVE_PYMOD_$1)=yes
+    else
+        AC_MSG_RESULT(no)
+        eval AS_TR_CPP(HAVE_PYMOD_$1)=no
+        #
+        if test -n "$2"
+        then
+            AC_MSG_ERROR(failed to find required module $1)
+            exit 1
+        fi
+    fi
+])
diff --git a/m4/check_python_venv.m4 b/m4/check_python_venv.m4
new file mode 100644
index 0000000000..fc1d19b296
--- /dev/null
+++ b/m4/check_python_venv.m4
@@ -0,0 +1,11 @@
+dnl Define DOVECOT_CHECK_PYTHON_VENV function to be used in configure.ac
+dnl Provide HAVE_VENV if we can access a virtual python environment,
+dnl which might be necessary to build the documentation if so desired.
+
+AC_DEFUN([DOVECOT_CHECK_PYTHON_VENV], [
+	AM_PATH_PYTHON([3.6],,[:])
+	AS_IF([test "${PYTHON}" != ":"], [
+		AX_PYTHON_MODULE([venv],[])
+	])
+	AM_CONDITIONAL([HAVE_VENV], [test "x${HAVE_PYMOD_VENV}" = "xyes"])
+])