Skip to content

Commit

Permalink
Makefile for php-src docs build
Browse files Browse the repository at this point in the history
In 19d2b84 ("Create book for docs", 2024-01-30) the php-src
documentation (php-src docs) build has been introduced, yet the build
instructions, namely `make html`, did not yield the expected results
within the parenting setup of the php-src project on *nix systems.

The reason is that the `make html` build instruction does not execute
the make.bat file which contains the recipe to build the static HTML
pages. This is because — different to Windows systems — *nix systems
do not have the concept of [COMSPEC] etc. for executables, and
therefore we cannot expect for build scripts an interpreter for the
batch file.

Adding a Makefile suffices to recover the build of php-src ./docs on a
*nix system.

NOTE: The "help" target has been intentionally left out as this Sphinx
builder [1] (with the same name) is not available in the configuration,
nor in use in CI (.github/workflows/docs.yml), and otherwise appeared
undocumented. Consequentially, the makefile goal does not include it,
as well as a target for any other unspecfied builder.

[COMSPEC]: https://en.wikipedia.org/wiki/COMSPEC "COMSPEC or ComSpec is one of the environment variables used in DOS, OS/2 and Windows, which normally points to the command line interpreter, which is by default COMMAND.COM in DOS,[1] Windows 95, 98, and ME or CMD.EXE in OS/2 and Windows NT. — Wikipedia"
[1]: https://www.sphinx-doc.org/en/master/usage/builders/index.html "Built-in Sphinx builders"
  • Loading branch information
hakre committed Nov 9, 2024
1 parent 63bd0f4 commit 1e82ef9
Showing 1 changed file with 29 additions and 0 deletions.
29 changes: 29 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# Makefile for php-src/docs
# Copyright (c) The PHP Group

# If people set these on the make command line, use 'em

SPHINXBUILD ?= sphinx-build
GH_PAGES_URL ?= https://php.github.io/php-src/

SOURCEDIR = source
BUILDDIR = build

rwildcard = $(foreach d,$(wildcard $(1:=/*)),$(call rwildcard,$d,$2) $(filter $(subst *,%,$2),$d))
FILES = $(call rwildcard,$(SOURCEDIR),*.rst)

all : html

.PHONY : clean html

clean :
rm -rf -- $(wildcard $(SOURCEDIR)/.~ $(BUILDDIR))

html : $(SOURCEDIR)/.~
$(SPHINXBUILD) -M $@ $(SOURCEDIR) $(BUILDDIR)
@printf 'Browse the php-src docs \e]8;;%s\e\\%s\e]8;;\e\\ (or \e]8;;%s\e\\%s\e]8;;\e\\)\n' \
"file://$(abspath $(BUILDDIR))/$@/index.$@" "local" "$(GH_PAGES_URL)" "online"

$(SOURCEDIR)/.~ : $(FILES)
rstfmt -w 100 $?
touch $@

0 comments on commit 1e82ef9

Please sign in to comment.