[freetype2] GSoC-2018-nikhil dfac4db: [builds] Add checks and targets for `docwriter'.

[Nikhil Ramakrishnan]

branch: GSoC-2018-nikhil
commit dfac4db6022365f4665331e0a31972f0743fd543
Author: Nikhil Ramakrishnan <address@hidden>
Commit: Nikhil Ramakrishnan <address@hidden>

    [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.
---
 builds/freetype.mk        | 65 ++++++++++++++++++++++++-----------------------
 builds/unix/configure.raw | 30 ++++++++++++++++++++++
 builds/unix/unix-def.in   |  5 ++++
 3 files changed, 68 insertions(+), 32 deletions(-)

diff --git a/builds/freetype.mk b/builds/freetype.mk
index 83aa52c..46a307d 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 9c342ad..aa67f86 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 be3737b..bc2350b 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'