Improve php-src docs sphinx build, also on *nix

.editorconfig

@@ -32,3 +32,7 @@ max_line_length          = 80
 
 [*.patch]
 trim_trailing_whitespace = false
+
+[*.rst]
+indent_style             = space
+max_line_length          = 100

.github/workflows/docs.yml

@@ -19,9 +19,9 @@ jobs:
       - name: git checkout
         uses: actions/checkout@v4
       - name: Install dependencies
-        run: pip install sphinx-design sphinxawesome-theme rstfmt
+        run: pip install -r docs/requirements.txt
       - name: Check formatting
-        run: rstfmt --check -w 100 docs/source
+        run: make -C docs check-formatting
       - name: Publish
         if: github.event_name == 'push'
         uses: sphinx-notes/pages@v3

docs/Makefile

@@ -0,0 +1,36 @@
+# Makefile for php-src/docs
+# Copyright (c) The PHP Group
+
+# If people set these on the make command line, use 'em
+
+SPHINXBUILD ?= sphinx-build
+
+SOURCEDIR = source
+BUILDDIR = build
+RSTFMT = rstfmt
+RSTFMTFLAGS = -w 100
+
+rwildcard = $(foreach d,$(wildcard $(1:=/*)),$(call rwildcard,$d,$2) $(filter $(subst *,%,$2),$d))
+FILES = $(call rwildcard,$(SOURCEDIR),*.rst)
+
+all : html
+
+.PHONY : check-formatting clean html preflight
+.SUFFIXES : # Disable legacy behavior
+
+check-formatting :
+	$(RSTFMT) $(RSTFMTFLAGS) --check $(SOURCEDIR)
+
+clean :
+	rm -rf -- $(wildcard $(SOURCEDIR)/.~ $(BUILDDIR))
+
+html : preflight
+	$(SPHINXBUILD) -M $@ $(SOURCEDIR) $(BUILDDIR)
+	@printf 'Browse the \e]8;;%s\e\\%s\e]8;;\e\\.\n' \
+		"file://$(abspath $(BUILDDIR))/$@/index.$@" "php-src html docs locally"
+
+preflight : $(SOURCEDIR)/.~
+
+$(SOURCEDIR)/.~ : $(FILES)
+	$(RSTFMT) $(RSTFMTFLAGS) $?
+	touch $@

docs/README.md

@@ -1,9 +1,10 @@
 # php-src docs
 
 This is the home of the php-src internal documentation, hosted at
-[php.github.io/php-src/](https://php.github.io/php-src/). It is in very early stages, but is
-intended to become the primary place where new information about php-src is documented. Over time,
-it is expected to replace various mediums like:
+[php.github.io/php-src/](https://php.github.io/php-src/). It is in very early
+stages, but is intended to become the primary place where new information about
+php-src is documented. Over time, it is expected to replace various mediums
+like:
 
 * https://www.phpinternalsbook.com/
 * https://wiki.php.net/internals
@@ -14,11 +15,15 @@ it is expected to replace various mediums like:
 `python` 3 and `pip` are required.
 
 ```bash
-pip install sphinx sphinx-design sphinxawesome-theme
+cd docs
+# Recommended: Initialize and activate a Python virtual environment
+pip install --upgrade pip
+pip install -r requirements.txt
 make html
 ```
 
-That's it! You can view the documentation under `./build/html/index.html` in your browser.
+That's it! You can view the documentation under `./build/html/index.html` in
+your browser.
 
 ## Formatting
 
@@ -29,5 +34,5 @@ The files in this documentation are formatted using the
 rstfmt -w 100 source
 ```
 
-This tool is not perfect. It breaks on custom directives, so we might switch to either a fork or
-something else in the future.
+This tool is not perfect. It breaks on custom directives, so we might switch to
+either a fork or something else in the future.

docs/requirements.txt

@@ -0,0 +1,4 @@
+Sphinx
+sphinx-design
+sphinxawesome-theme
+rstfmt

docs/source/conf.py

@@ -16,7 +16,6 @@
 author = 'The PHP Group'
 extensions = [
     'sphinx_design',
-    'sphinxawesome_theme.highlighting',
 ]
 templates_path = ['_templates']
 html_theme = 'sphinxawesome_theme'