add phpDocumentor instructions to Makefile (#1385)

* add phpDocumentor instructions to Makefile

Signed-off-by: svrnm <neumanns@cisco.com>

* update DEVELOPMENT.md

Signed-off-by: svrnm <neumanns@cisco.com>

---------

Signed-off-by: svrnm <neumanns@cisco.com>

.gitignore

@@ -30,3 +30,9 @@ tests/TraceContext/W3CTestService/trace-context
 
 # deptrac cache
 /.deptrac.cache
+
+# output from phpdoc 
+docs/build
+
+# cache from phpdoc
+.phpdoc

DEVELOPMENT.md

@@ -236,3 +236,21 @@ make phpmetrics
 
 This will generate a HTML PhpMetrics report in the `var/metrics` directory. Make sure to run `make test` before to
 create the test log-file, used by the metrics report.
+
+## API Documentation
+
+We use [phpDocumentor](https://phpdoc.org/) to automatically generate API documentation from DocBlocks in the code.
+
+To generate a recent version of the API documentation, you can run:
+
+```bash
+make phpdoc
+```
+
+To preview the documentation and changes you might expect, you can run:
+
+```bash
+make phpdoc-preview
+```
+
+This will start a HTTP server running at <http://localhost:8080> serving the updated documentation files.

Makefile

@@ -41,6 +41,10 @@ psalm: ## Run psalm
 	$(DC_RUN_PHP) env XDEBUG_MODE=off vendor-bin/psalm/vendor/bin/psalm --threads=1 --no-cache
 psalm-info: ## Run psalm and show info
 	$(DC_RUN_PHP) env XDEBUG_MODE=off vendor-bin/psalm/vendor/bin/psalm --show-info=true --threads=1
+phpdoc: ## Run phpdoc
+	$(DOCKER_COMPOSE) -f docker-compose.phpDocumentor.yaml run --rm phpdoc
+phpdoc-preview:
+	$(DOCKER_COMPOSE) -f docker-compose.phpDocumentor.yaml run --service-ports --rm preview
 phpstan: ## Run phpstan
 	$(DC_RUN_PHP) env XDEBUG_MODE=off vendor/bin/phpstan analyse --memory-limit=256M
 infection: ## Run infection (mutation testing)

docker-compose.phpDocumentor.yaml

@@ -0,0 +1,11 @@
+services:
+  phpdoc:
+    image: phpdoc/phpdoc:3
+    volumes:
+      - ./:/data
+  preview:
+    image: nginx:alpine
+    ports:
+      - 8080:80
+    volumes:
+      - ./docs/build:/usr/share/nginx/html

phpdoc.dist.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<phpdocumentor
+        configVersion="3"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xmlns="https://www.phpdoc.org"
+>
+    <title>OpenTelemetry PHP</title>
+    <paths>
+        <output>docs/build</output>
+    </paths>
+</phpdocumentor>