[builds] Add checks and targets for `docwriter'.

Add checks for Python, pip and docwriter. Docwriter is now a PyPI
package, downloadable from

  https://pypi.org/project/docwriter/

This package can be installed with the command `pip install docwriter'
on any system that has pip.

Running `make' on a fresh build will now warn if package `docwriter' is
not installed, and also provide information about the `make refdoc-venv'
alternative.

* builds/freetype.mk: Modify targats `refdoc' and `refdoc-venv' to
use detected python version/alias, and run docwriter as a package.

* builds/unix/configure.raw: Add rules to check python, pip and
docwriter. (code discussed in the dev mailing list).

* builds/unix/unix-def.in: Add variables PYTHON and PIP detected by
`configure.ac'. This is conditionally assigned (if empty) in
`freetype.mk' to the defaults.

3 files changed, 68 insertions, 32 deletions

diff --git a/builds/freetype.mk b/builds/freetype.mk
index 83aa52c09..46a307dd3 100644
--- a/builds/freetype.mk
+++ b/builds/freetype.mk
@@ -289,49 +289,50 @@ objects: $(OBJECTS_LIST)
 
 library: $(PROJECT_LIBRARY)
 
-
+# Run `docwriter' in the current Python environment.
+# We first check if package is installed using the pip option `show'
 # Option `-B' disables generation of .pyc files (available since python 2.6)
 #
+
+PYTHON ?= python
+PIP    ?= pip
+
 refdoc:
-	@echo Installing requirements...
-	python -m pip install --user -r \
-                        $(SRC_DIR)/tools/docwriter/requirements.txt
-	@echo "Running docwriter..."
-	python -B $(SRC_DIR)/tools/docwriter/docwriter.py \
-                  --prefix=ft2                          \
-                  --title=FreeType-$(version)           \
-                  --output=$(DOC_DIR)                   \
-                  $(PUBLIC_DIR)/*.h                     \
-                  $(PUBLIC_DIR)/config/*.h              \
-                  $(PUBLIC_DIR)/cache/*.h
+	@echo Running docwriter...
+	$(PYTHON) -m docwriter                          \
+				--prefix=ft2                        \
+				--title=FreeType-$(version)         \
+				--output=$(DOC_DIR)                 \
+				$(PUBLIC_DIR)/*.h                   \
+				$(PUBLIC_DIR)/config/*.h            \
+				$(PUBLIC_DIR)/cache/*.h
 	@echo Building static site...
 	cd $(DOC_DIR) && mkdocs build
 	@echo Done.
 
-# Variables for running refdoc with Python's `virtualenv'.
-# The env is created in `DOC_DIR/env' and is gitignored.
-# We still need to cd into `DOC_DIR' to build mkdocs because
-# paths in mkdocs.yml are relative to cwd.
+# Variables for running refdoc with Python's `virtualenv'. The env is
+# created in `DOC_DIR/env' and is gitignored.
+# We still need to cd into `DOC_DIR' to build mkdocs because paths in
+# mkdocs.yml are relative to cwd.
 #
-VENV_NAME     := env
-IN_VENV       := $(DOC_DIR)$(SEP)$(VENV_NAME)
-VENV_ACTIVATE := $(IN_VENV)$(SEP)$(BIN)$(SEP)activate
-PYTHON        := $(IN_VENV)$(SEP)$(BIN)$(SEP)python
-PIP           := $(IN_VENV)$(SEP)$(BIN)$(SEP)pip
+VENV_NAME  := env
+VENV_DIR   := $(DOC_DIR)$(SEP)$(VENV_NAME)
+ENV_PYTHON := $(VENV_DIR)$(SEP)$(BIN)$(SEP)$(PYTHON)
+ENV_PIP    := $(VENV_DIR)$(SEP)$(BIN)$(SEP)$(PIP)
 
 refdoc-venv:
 	@echo Setting up virtualenv for Python...
-	virtualenv $(IN_VENV)
-	@echo Installing requirements...
-	$(PIP) install -r $(SRC_DIR)/tools/docwriter/requirements.txt
-	@echo "Running docwriter..."
-	$(PYTHON) -B $(SRC_DIR)/tools/docwriter/docwriter.py  \
-                  --prefix=ft2                          \
-                  --title=FreeType-$(version)           \
-                  --output=$(DOC_DIR)                   \
-                  $(PUBLIC_DIR)/*.h                     \
-                  $(PUBLIC_DIR)/config/*.h              \
-                  $(PUBLIC_DIR)/cache/*.h
+	virtualenv $(VENV_DIR)
+	@echo Installing docwriter...
+	$(ENV_PIP) install docwriter
+	@echo Running docwriter...
+	$(ENV_PYTHON) -m docwriter                      \
+					--prefix=ft2                    \
+					--title=FreeType-$(version)     \
+					--output=$(DOC_DIR)             \
+					$(PUBLIC_DIR)/*.h               \
+					$(PUBLIC_DIR)/config/*.h        \
+					$(PUBLIC_DIR)/cache/*.h
 	@echo Building static site...
 	cd $(DOC_DIR) && $(VENV_NAME)$(SEP)$(BIN)$(SEP)python -m mkdocs build
 	@echo Done.
diff --git a/builds/unix/configure.raw b/builds/unix/configure.raw
index 9c342ad6a..aa67f869a 100644
--- a/builds/unix/configure.raw
+++ b/builds/unix/configure.raw
@@ -968,6 +968,25 @@ case "$CFLAGS" in
     ;;
 esac
 
+# Check for python and docwriter
+
+AC_CHECK_PROGS([PYTHON], [python python2 python3], [missing])
+have_docwriter=no
+if test "x$PYTHON" != "xmissing"; then
+  AC_CHECK_PROGS([PIP], [pip pip2 pip3], [missing])
+
+  if test "x$PIP" != "xmissing"; then
+    AC_MSG_CHECKING([for \`docwriter' Python module])
+    $PIP show -q docwriter
+    if test "x$?" = "x0"; then
+      have_docwriter=yes
+      AC_MSG_RESULT([yes])
+    else
+      AC_MSG_RESULT([no])
+    fi
+  fi
+fi
+
 
 # entries in Requires.private are separated by commas;
 REQUIRES_PRIVATE="$zlib_reqpriv,     \
@@ -1112,4 +1131,15 @@ Library configuration:
   harfbuzz:      $have_harfbuzz
 ])
 
+# Warn if docwriter is not installed
+
+if test $have_docwriter = no; then
+  AC_MSG_NOTICE([
+  Warning: \`make refdoc' will fail since pip package \`docwriter' is not
+  installed.  To install, run \`$PIP install docwriter', or to use a python
+  virtual environment, run \`make refdoc-venv' (requires pip package
+  \`virtualenv').
+  ])
+fi
+
 # end of configure.raw
diff --git a/builds/unix/unix-def.in b/builds/unix/unix-def.in
index be3737b07..bc2350b37 100644
--- a/builds/unix/unix-def.in
+++ b/builds/unix/unix-def.in
@@ -20,6 +20,11 @@ DELETE := rm -f
 DELDIR := rm -rf
 CAT    := cat
 SEP    := /
+
+# this is used for `make refdoc' and `make refdoc-venv'
+#
+PYTHON := @PYTHON@
+PIP    := @PIP@
 BIN    := bin
 
 # this is used for `make distclean' and `make install'