Commit c962db28ea59225f0105c03d907d4a9b71765687
2018-08-25T12:22:23
* 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'.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244
diff --git a/Jamfile b/Jamfile
index 9078a5f..6546213 100644
--- a/Jamfile
+++ b/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 ;
diff --git a/builds/ansi/ansi-def.mk b/builds/ansi/ansi-def.mk
index 1484f96..38571a5 100644
--- a/builds/ansi/ansi-def.mk
+++ b/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.
#
diff --git a/builds/beos/beos-def.mk b/builds/beos/beos-def.mk
index 89c54dd..5a3b520 100644
--- a/builds/beos/beos-def.mk
+++ b/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.
#
diff --git a/builds/dos/dos-def.mk b/builds/dos/dos-def.mk
index cb1154d..434f61b 100644
--- a/builds/dos/dos-def.mk
+++ b/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.
#
diff --git a/builds/freetype.mk b/builds/freetype.mk
index 6f68a0f..356aa70 100644
--- a/builds/freetype.mk
+++ b/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
diff --git a/builds/os2/os2-def.mk b/builds/os2/os2-def.mk
index 7ad1ffb..7c19a5c 100644
--- a/builds/os2/os2-def.mk
+++ b/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
diff --git a/builds/unix/configure.raw b/builds/unix/configure.raw
index f18bb3d..769c44e 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], [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
diff --git a/builds/unix/unix-def.in b/builds/unix/unix-def.in
index 6957053..7e824bc 100644
--- a/builds/unix/unix-def.in
+++ b/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)
diff --git a/builds/unix/unixddef.mk b/builds/unix/unixddef.mk
index a8da63a..e45e751 100644
--- a/builds/unix/unixddef.mk
+++ b/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
diff --git a/builds/windows/win32-def.mk b/builds/windows/win32-def.mk
index f83d444..2a91847 100644
--- a/builds/windows/win32-def.mk
+++ b/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