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 6d14ec68fe699d67e0ae8954d4341ae758adf1f7..be1d3d11b387a8a71fe3e0ea09a1cbb764afacb0 100644 (file)
--- 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 f61b204c18d750e7859d2514342c132c0aef3ca0..ffb4a50df4eed3687c4f64d0d7221c2fd88cd4bd 100644 (file)
--- 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 4db1b86af3d5a69dc25717032d97f5bf2d7e2ed4..2b939b37e2d6c5cc27da20b8ec7d407587734883 100644 (file)
--- 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 (file)
index 0000000..f0f873d
--- /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 (file)
index 0000000..fc1d19b
--- /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"])
+])