From 91f4735b3a3f0c85b032cc864469f208a9f1f851 Mon Sep 17 00:00:00 2001
From: Severin Neumann <neumanns@cisco.com>
Date: Wed, 25 Sep 2024 20:39:36 +0200
Subject: [PATCH] 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                        |  6 ++++++
 DEVELOPMENT.md                    | 18 ++++++++++++++++++
 Makefile                          |  4 ++++
 docker-compose.phpDocumentor.yaml | 11 +++++++++++
 phpdoc.dist.xml                   | 11 +++++++++++
 5 files changed, 50 insertions(+)
 create mode 100644 docker-compose.phpDocumentor.yaml
 create mode 100644 phpdoc.dist.xml

diff --git a/.gitignore b/.gitignore
index 39b37c4dd..b95376955 100644
--- a/.gitignore
+++ b/.gitignore
@@ -30,3 +30,9 @@ tests/TraceContext/W3CTestService/trace-context
 
 # deptrac cache
 /.deptrac.cache
+
+# output from phpdoc 
+docs/build
+
+# cache from phpdoc
+.phpdoc
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 87d6edd4e..69f0b9019 100644
--- a/DEVELOPMENT.md
+++ b/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.
\ No newline at end of file
diff --git a/Makefile b/Makefile
index 8538ca84d..ed7685c5c 100644
--- a/Makefile
+++ b/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)
diff --git a/docker-compose.phpDocumentor.yaml b/docker-compose.phpDocumentor.yaml
new file mode 100644
index 000000000..5cfe5e643
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/phpdoc.dist.xml b/phpdoc.dist.xml
new file mode 100644
index 000000000..58bab8faa
--- /dev/null
+++ b/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>
\ No newline at end of file