+phpdoc

Author: codemasher

.github/workflows/tests.yml

@@ -2,8 +2,13 @@
 # https://github.com/sebastianbergmann/phpunit/blob/master/.github/workflows/ci.yml
 
 on:
-  - pull_request
-  - push
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
 
 name: "CI"
 
@@ -36,6 +41,33 @@ jobs:
       - name: "Run phan"
         run: php vendor/bin/phan
 
+  build-docs:
+    name: "Build and publish Docs"
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: "Checkout sources"
+        uses: actions/checkout@v2
+
+      - name: "Install PHP"
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "7.4"
+          coverage: none
+          tools: phpDocumentor
+          extensions: json
+
+      - name: "Build Docs"
+        run: phpdoc --config=phpdoc.xml
+
+      - name: "Publish Docs to gh-pages"
+        uses: JamesIves/[email protected]
+        with:
+          BRANCH: gh-pages
+          FOLDER: docs
+          CLEAN: true
+
   tests:
     name: "Unit Tests"
 
@@ -50,7 +82,7 @@ jobs:
         php-version:
           - "7.4"
           - "8.0"
-#          - "8.1"
+          - "8.1"
 
     steps:
       - name: "Configure git to avoid issues with line endings"

docs/Readme.md

@@ -0,0 +1,13 @@
+# Auto generated API documentation
+
+The API documentation can be auto generated with [phpDocumentor](https://www.phpdoc.org/). 
+There is an [online version available](https://chillerlan.github.io/php-settings-container/) via the [gh-pages branch](https://github.com/chillerlan/php-settings-container/tree/gh-pages) that is [automatically deployed](https://github.com/chillerlan/php-settings-container/deployments) on each push to main.
+
+Locally created docs will appear in this directory. If you'd like to create local docs, please follow these steps:
+
+- [download phpDocumentor](https://github.com/phpDocumentor/phpDocumentor/releases) v3+ as .phar archive
+- run it in the repository root directory:
+  - on Windows `c:\path\to\php.exe c:\path\to\phpDocumentor.phar --config=phpdoc.xml`
+  - on Linux just `php /path/to/phpDocumentor.phar --config=phpdoc.xml`
+- open [index.html](./index.html) in a browser
+- profit!

phpdoc.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<phpdoc>
+	<parser>
+		<target>docs</target>
+		<encoding>utf8</encoding>
+		<markers>
+			<item>TODO</item>
+		</markers>
+	</parser>
+	<transformer>
+		<target>docs</target>
+	</transformer>
+	<files>
+		<directory>src</directory>
+		<directory>tests</directory>
+	</files>
+	<transformations>
+		<template name="responsive-twig"/>
+	</transformations>
+</phpdoc>