feat(DX): enhancement doc with docker + makefile + feature workflow (#267)

.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}

.gitattributes

@@ -0,0 +1,2 @@
+*.xml linguist-detectable
+*.ent linguist-language=XML linguist-detectable

.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

.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 }}"

.gitignore

@@ -1 +1,3 @@
 entities.*.xml
+output
+.docker/built

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

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.