ref: c962db28ea59225f0105c03d907d4a9b71765687
parent: 195728d5ba38f34fb2c2c20807c01656f2f59b66
author: Nikhil Ramakrishnan <[email protected]>
date: Sat Aug 25 08:22:23 EDT 2018
* 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'.
--- a/Jamfile
+++ b/Jamfile
@@ -208,12 +208,13 @@
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 ;
--- a/builds/ansi/ansi-def.mk
+++ b/builds/ansi/ansi-def.mk
@@ -19,6 +19,9 @@
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.
#
--- a/builds/beos/beos-def.mk
+++ b/builds/beos/beos-def.mk
@@ -21,6 +21,9 @@
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.
#
--- a/builds/dos/dos-def.mk
+++ b/builds/dos/dos-def.mk
@@ -19,6 +19,9 @@
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.
#
--- 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 @@
library: $(PROJECT_LIBRARY)
-
+# Run `docwriter' in the current Python environment.
# Option `-B' disables generation of .pyc files (available since python 2.6)
#
+
+PYTHON ?= python
+PIP ?= pip
+
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
+ @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
--- a/builds/os2/os2-def.mk
+++ b/builds/os2/os2-def.mk
@@ -19,6 +19,10 @@
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
--- a/builds/unix/configure.raw
+++ b/builds/unix/configure.raw
@@ -968,7 +968,26 @@
;;
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, \
$bzip2_reqpriv, \
@@ -1111,5 +1130,16 @@
libpng: $have_libpng
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
--- a/builds/unix/unix-def.in
+++ b/builds/unix/unix-def.in
@@ -21,6 +21,12 @@
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)
--- a/builds/unix/unixddef.mk
+++ b/builds/unix/unixddef.mk
@@ -23,6 +23,10 @@
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
--- a/builds/windows/win32-def.mk
+++ b/builds/windows/win32-def.mk
@@ -19,6 +19,10 @@
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