From a4dd094a9034b4b75bc69340641f518067f65c3f Mon Sep 17 00:00:00 2001
From: Philippe DELENTE <80407535+PhilDaiguille@users.noreply.github.com>
Date: Sun, 27 Jul 2025 14:51:08 +0200
Subject: [PATCH] feat(DX): enhancement doc with docker + makefile + feature
 workflow (#267)

---
 .docker/Dockerfile                     | 19 +++++++++++++++
 .gitattributes                         |  2 ++
 .github/workflows/check-whitespace.yml | 29 +++++++++++++++++++++++
 .github/workflows/integrate.yaml       |  5 ++++
 .gitignore                             |  2 ++
 Makefile                               | 32 ++++++++++++++++++++++++++
 README.md                              | 10 ++++++++
 7 files changed, 99 insertions(+)
 create mode 100644 .docker/Dockerfile
 create mode 100644 .gitattributes
 create mode 100644 .github/workflows/check-whitespace.yml
 create mode 100644 Makefile

diff --git a/.docker/Dockerfile b/.docker/Dockerfile
new file mode 100644
index 000000000..40a9bc44a
--- /dev/null
+++ b/.docker/Dockerfile
@@ -0,0 +1,19 @@
+FROM php:8.2-cli
+
+RUN apt-get update && \
+    apt-get install -y git default-jre-headless
+
+WORKDIR /var/www
+
+ADD https://api.github.com/repos/php/phd/git/refs/heads/master version-phd.json
+ADD https://api.github.com/repos/php/doc-base/git/refs/heads/master version-doc-base.json
+
+RUN git clone --depth 1 https://github.com/php/phd.git &&  \
+    git clone --depth 1 https://github.com/php/doc-base.git
+
+RUN echo 'memory_limit = 512M' >> /usr/local/etc/php/conf.d/local.ini
+
+ENV FORMAT=xhtml
+
+CMD php doc-base/configure.php --disable-segfault-error && \
+    php phd/render.php --docbook doc-base/.manual.xml --output=/var/www/en/output --package PHP --format ${FORMAT}
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 000000000..dcc145fb1
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,2 @@
+*.xml linguist-detectable
+*.ent linguist-language=XML linguist-detectable
diff --git a/.github/workflows/check-whitespace.yml b/.github/workflows/check-whitespace.yml
new file mode 100644
index 000000000..dce72effb
--- /dev/null
+++ b/.github/workflows/check-whitespace.yml
@@ -0,0 +1,29 @@
+name: check-whitespace
+
+# Get the repository with all commits to ensure that we can analyze
+# all of the commits contributed via the Pull Request.
+# Process `git log --check` output to extract just the check errors.
+# Exit with failure upon white-space issues.
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+permissions:
+  contents: read
+
+jobs:
+  check-whitespace:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - run: |
+          git config --global user.name "check-whitespace"
+          git config --global user.email "check-whitespace@example.com"
+      - run: git checkout ${{github.event.pull_request.base.sha}}
+      - run: git merge --squash ${{github.event.pull_request.head.sha}}
+      - run: git commit -m "Squashed"
+      - run: git log --check HEAD^..HEAD
diff --git a/.github/workflows/integrate.yaml b/.github/workflows/integrate.yaml
index 53271a316..3cb116ae7 100644
--- a/.github/workflows/integrate.yaml
+++ b/.github/workflows/integrate.yaml
@@ -39,5 +39,10 @@ jobs:
           path: "doc-base"
           repository: "php/doc-base"
 
+      - name: "Quality Assurance scripts"
+        run: |
+          php8.1 doc-base/scripts/qa/extensions.xml.php --check
+          php8.1 doc-base/scripts/qa/section-order.php
+
       - name: "Build documentation for ${{ matrix.language }}"
         run: "php8.1 doc-base/configure.php --disable-libxml-check --enable-xml-details --redirect-stderr-to-stdout --with-lang=${{ matrix.language }}"
diff --git a/.gitignore b/.gitignore
index b2f1b48fa..15671bf14 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,3 @@
 entities.*.xml
+output
+.docker/built
diff --git a/Makefile b/Makefile
new file mode 100644
index 000000000..8b0cb04e7
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,32 @@
+	.PHONY: *
+
+SHELL = /bin/sh
+
+CURRENT_UID := $(shell id -u)
+CURRENT_GID := $(shell id -g)
+
+#
+# If doc-base or phd exist as siblings to the current directory, add those as
+# volumes to our Docker runs.
+#
+
+PATHS := -v .:/var/www/en
+ifneq ($(wildcard ../doc-base/LICENSE),)
+	PATHS += -v ${PWD}/../doc-base:/var/www/doc-base
+endif
+ifneq ($(wildcard ../phd/LICENSE),)
+	PATHS += -v ${PWD}/../phd:/var/www/phd
+endif
+
+xhtml: .docker/built
+	docker run --rm ${PATHS} -w /var/www -u ${CURRENT_UID}:${CURRENT_GID} php/doc-en
+
+php: .docker/built
+	docker run --rm ${PATHS} -w /var/www -u ${CURRENT_UID}:${CURRENT_GID} \
+		-e FORMAT=php php/doc-en
+
+build: .docker/built
+
+.docker/built:
+	docker build .docker -t php/doc-en
+	touch .docker/built
diff --git a/README.md b/README.md
index deec972ac..1123e14b2 100644
--- a/README.md
+++ b/README.md
@@ -34,3 +34,13 @@ Por favor, consulta para saber más detalles.
 Por favor date de alta en la lista de correo oficial: <doc-es-subscribe@lists.php.net> desde [PHP Docs ES Mailing List](https://news-web.php.net/php.doc.es), o enviando un correo en blanco a <doc-es+subscribe@lists.php.net>.
 
 O en otras Mailing Lists de PHP desde [PHP Mailing Lists](https://www.php.net/mailing-lists.php).
+
+## Construyendo con make y Docker
+
+- Instala Docker (https://docs.docker.com/get-docker/)
+- Reconstruye la documentación usando `make`
+- Abre output/php-chunked-xhtml/ en tu navegador.
+
+Si los repositorios `doc-base` o `phd` están disponibles en directorios adyacentes a este directorio, esos se utilizarán para la construcción. Para forzar que la imagen de Docker utilizada para la construcción se reconstruya a sí misma, puedes ejecutar `make -B build`; de lo contrario, el `Makefile` solo la construirá si no existe ya.
+
+También puedes construir la versión `web` de la documentación con `make php` y la salida se colocará en output/php-web.