* builds/*/*: Prepare build system for docwriter.

Add checks, rules and variables to the build system for docwriter.

* Running `make' will warn if Python/PIP/docwriter are not available.

* Running `make refdoc' will generate static documentation site on the
current Python environment.

* Running `make refdoc-venv' will generate static documentation site
using a virtual environment, using the pip package `virtualenv'.

Author: nikramakrishnan

Jamfile

@@ -208,12 +208,13 @@ rule RefDoc
 
 actions RefDoc
 {
-  python $(FT2_SRC)/tools/docmaker/docmaker.py
+  python -m docwriter
          --prefix=ft2
          --title=FreeType-2.9.1
          --output=$(DOC_DIR)
          $(FT2_INCLUDE)/freetype/*.h
          $(FT2_INCLUDE)/freetype/config/*.h
+         $(FT2_INCLUDE)/freetype/cache/*.h
 }
 
 RefDoc  refdoc ;

builds/ansi/ansi-def.mk

@@ -19,6 +19,9 @@ SEP       := /
 BUILD_DIR := $(TOP_DIR)/builds/ansi
 PLATFORM  := ansi
 
+# This is used for `make refdoc' and `make refdoc-venv'
+#
+BIN := bin
 
 # The directory where all library files are placed.
 #

builds/beos/beos-def.mk

@@ -21,6 +21,9 @@ SEP       := /
 BUILD_DIR := $(TOP_DIR)/builds/beos
 PLATFORM  := beos
 
+# This is used for `make refdoc' and `make refdoc-venv'
+#
+BIN := bin
 
 # The directory where all library files are placed.
 #

builds/dos/dos-def.mk

@@ -19,6 +19,9 @@ SEP       := $(strip \ )
 BUILD_DIR := $(TOP_DIR)/builds/dos
 PLATFORM  := dos
 
+# This is used for `make refdoc' and `make refdoc-venv'
+#
+BIN := Scripts
 
 # The executable file extension (for tools), *with* leading dot.
 #

builds/freetype.mk

@@ -75,7 +75,7 @@
 # The targets `objects' and `library' are defined at the end of this
 # Makefile after all other rules have been included.
 #
-.PHONY: single multi objects library refdoc
+.PHONY: single multi objects library refdoc refdoc-venv
 
 # default target -- build single objects and library
 #
@@ -289,18 +289,52 @@ objects: $(OBJECTS_LIST)
 
 library: $(PROJECT_LIBRARY)
 
-
+# Run `docwriter' in the current Python environment.
 # Option `-B' disables generation of .pyc files (available since python 2.6)
 #
-refdoc:
-	python -B $(SRC_DIR)/tools/docmaker/docmaker.py \
-                  --prefix=ft2                          \
-                  --title=FreeType-$(version)           \
-                  --output=$(DOC_DIR)                   \
-                  $(PUBLIC_DIR)/*.h                     \
-                  $(PUBLIC_DIR)/config/*.h              \
-                  $(PUBLIC_DIR)/cache/*.h
 
+PYTHON ?= python
+PIP    ?= pip
+
+refdoc:
+	@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.
+#
+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 $(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.
 
 .PHONY: clean_project_std distclean_project_std
 

builds/os2/os2-def.mk

@@ -19,6 +19,10 @@ SEP       := $(strip \ )
 BUILD_DIR := $(TOP_DIR)/builds/os2
 PLATFORM  := os2
 
+# This is used for `make refdoc' and `make refdoc-venv'
+#
+BIN := Scripts
+
 # The executable file extension (for tools), *with* leading dot.
 #
 E := .exe

builds/unix/configure.raw

@@ -968,6 +968,25 @@ case "$CFLAGS" in
     ;;
 esac
 
+# Check for python and docwriter
+
+AC_CHECK_PROGS([PYTHON], [python3 python2 python], [missing])
+have_docwriter=no
+if test "x$PYTHON" != "xmissing"; then
+  AC_CHECK_PROGS([PIP], [pip3 pip2 pip], [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

builds/unix/unix-def.in

@@ -21,6 +21,12 @@ 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'
 OBJ_BUILD ?= $(BUILD_DIR)
 

builds/unix/unixddef.mk

@@ -23,6 +23,10 @@ DELETE := rm -f
 CAT    := cat
 SEP    := /
 
+# This is used for `make refdoc' and `make refdoc-venv'
+#
+BIN := bin
+
 # we use a special devel ftoption.h
 DEVEL_DIR := $(TOP_DIR)/devel
 

builds/windows/win32-def.mk

@@ -19,6 +19,10 @@ SEP       := $(strip \ )
 BUILD_DIR := $(TOP_DIR)/builds/windows
 PLATFORM  := windows
 
+# This is used for `make refdoc' and `make refdoc-venv'
+#
+BIN := Scripts
+
 # The executable file extension (for tools). NOTE: WE INCLUDE THE DOT HERE !!
 #
 E := .exe