[FEAT] add watch option

The new `--watch` flag on the run command will help documentation
writers to have a "live" rerendering of their documentation. The
command will run the normal rendering once, then changes to existing
files are detected and will trigger a rerender of the changed file.

To speed up the rendering only the changed file is compiled, this
might cause issues in the menu. But that should not be an issue as
the final result is always based on a full render.

Author: jaapio

.dockerignore

@@ -5,4 +5,7 @@ tools/
 vendor/
 Dockerfile
 *.rst
-build
+.Build
+Documentation*
+.phpdoc
+.cache

.github/workflows/main.yaml

@@ -31,6 +31,7 @@ jobs:
         with:
           coverage: "none"
           php-version: "${{ matrix.php }}"
+          extensions: 'inotify, pcntl'
 
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v2"
@@ -55,6 +56,7 @@ jobs:
         with:
           coverage: "none"
           php-version: "${{ env.DEFAULT_PHP_VERSION }}"
+          extensions: 'inotify, pcntl'
 
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v2"
@@ -91,6 +93,7 @@ jobs:
         with:
           coverage: "none"
           php-version: "${{ env.DEFAULT_PHP_VERSION }}"
+          extensions: 'inotify, pcntl'
 
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v2"

Dockerfile

@@ -1,4 +1,10 @@
-FROM composer:2 AS builder
+FROM php:8.1-cli-alpine AS builder
+
+COPY --from=ghcr.io/php/pie:bin /pie /usr/bin/pie
+COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
+
+RUN apk add --update $PHPIZE_DEPS
+RUN pie install arnaud-lb/inotify && docker-php-ext-install pcntl
 
 WORKDIR /opt/guides
 COPY . /opt/guides
@@ -7,6 +13,13 @@ RUN composer install --no-dev --no-interaction --no-progress  \
     --no-suggest --optimize-autoloader --classmap-authoritative
 
 FROM php:8.1-cli-alpine
+
+COPY --from=ghcr.io/php/pie:bin /pie /usr/bin/pie
+RUN apk add --update $PHPIZE_DEPS
+RUN pie install arnaud-lb/inotify && docker-php-ext-install pcntl
+
+RUN apk del $PHPIZE_DEPS && rm -rf /var/cache/apk/* /tmp/* /usr/share/php/* /usr/local/lib/php/doc/* /usr/local/lib/php/test/*
+
 COPY . /opt/guides
 WORKDIR /opt/guides
 

Makefile

@@ -7,7 +7,7 @@ PHP_BIN ?= docker run -i --rm --user $$(id -u):$$(id -g) -v${PWD}:/opt/project -
 
 ## Docker wrapper to use for a typo3-docs:local container.
 ## This container provides a runtime for the `guides` project
-PHP_PROJECT_BIN ?= docker run -i --rm --user $$(id -u):$$(id -g) -v${PWD}:/project typo3-docs:local
+PHP_PROJECT_BIN ?= docker run -i --rm --user $$(id -u):$$(id -g) -v${PWD}:/project --entrypoint=/project/vendor/bin/guides -p 1337:1337 typo3-docs:local
 
 ## Docker wrapper to use for a typo3-docs:local container.
 ## This container provides a composer-runtime; mounts project on /app
@@ -128,7 +128,7 @@ test: test-integration test-unit test-xml test-docs test-rendertest ## Runs all
 .PHONY: test-docs
 test-docs: ## Runs project generation tests
 	@echo "$(ENV_INFO)"
-	$(PHP_BIN) vendor/bin/guides --no-progress Documentation --output="/tmp/test" --config=Documentation --minimal-test
+	$(PHP_PROJECT_BIN) --no-progress Documentation --config=Documentation --minimal-test
 
 .PHONY: test-rendertest
 test-rendertest: ## Runs rendering with Documentation-rendertest

composer.json

@@ -9,6 +9,7 @@
         "ext-libxml": "*",
         "brotkrueml/twig-codehighlight": "^1.0",
         "league/flysystem": "^1.1.10",
+        "phpdocumentor/dev-server": "^1.9",
         "phpdocumentor/filesystem": "^1.9",
         "phpdocumentor/guides": "^1.9",
         "phpdocumentor/guides-cli": "^1.9",
@@ -17,9 +18,11 @@
         "phpdocumentor/guides-restructured-text": "^1.9",
         "phpdocumentor/guides-theme-bootstrap": "^1.7",
         "phpdocumentor/guides-theme-rst": "^1.7",
+        "psr/http-message": "^1.1",
         "symfony/clock": "^6.4",
         "symfony/finder": "^6.4",
         "symfony/http-client": "^6.4",
+        "symfony/polyfill-php84": "^1.33",
         "symfony/yaml": "^6.4",
         "t3docs/console-command": "^0.2.0",
         "t3docs/guides-php-domain": "^1.0",