✨ Add php doc generator

.github/workflows/docs.yml

@@ -0,0 +1,44 @@
+# Original by Turadg Aleahmad licensed as MIT
+# https://github.com/actions/starter-workflows/pull/2255/files
+
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+
+  workflow_dispatch:
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  pages:
+    runs-on: ubuntu-20.04
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+      - name: Generate API Docs
+        uses: phpDocumentor/phpDocumentor@master
+        with:
+          args:  --validate -v
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: ./docs/build
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v3

.gitignore

@@ -120,7 +120,9 @@ fabric.properties
 build
 composer.lock
 coverage
-docs
 phpunit.xml
 phpstan.neon
 testbench.yaml
+phpdoc
+.phpdoc/cache
+docs/build

README.md

@@ -27,31 +27,9 @@ You can publish the config file with:
 php artisan vendor:publish --tag="audit-config"
 ```
 
-## Usage
+## Documentation
 
-To gather the results of the checks, make a call to `/api/route`. The result is an array of all checks, with their name,
-group, status and some description for non-successful checks. Checks can result in a success (which is fine), an info
-(which might depend on your situation), a warning (which is likely problematic) or a fatal (which is almost always
-unwanted).
-
-You can configure the checks and some behaviour in the `config/audit.php` after publishing the config file. You should
-most probably add a middleware to restrict the access to the route.
-
-You can also use artisan. Note that this is only really useful for testing or if you have the same php configuration
-for the CLI and the webserver which if you are not sure is probably not the case. It is advised to always check this
-result against the result of `/api/route`. To execute the command, execute `php artisan audit`. You can pass group
-names as arguments to only execute these groups. The exit code is `1` if and only if a non-successful check was
-executed. You can also exclude check states, to list the available options execute the `--help` option.
-
-## Plugins
-
-If you want to create your own checks instead of working on the original repo, you can simple let your checks extend
-the abstract \Hexafuchs\Audit\Checks\Check class or implement the \Hexafuchs\Audit\Checks\Checkable interface, then
-merge your checks into the audit.checks config array.
-
-You can also not implement the interface if you want to have another return type, all checks in audit.checks that
-contain an execute function will be executed with no arguments. Note that you will not be able to have colored output
-in the artisan command for other status values.
+You can find the entire documentation at [https://hexafuchs.github.io/:package_name/](https://hexafuchs.github.io/:package_name/guide/getting-started/index.html).
 
 ## Testing
 

composer.json

@@ -35,8 +35,7 @@
     },
     "autoload": {
         "psr-4": {
-            "Hexafuchs\\Audit\\": "src/",
-            "Hexafuchs\\Audit\\Database\\Factories\\": "database/factories/"
+            "Hexafuchs\\Audit\\": "src/"
         }
     },
     "autoload-dev": {
@@ -61,7 +60,9 @@
         "analyse": "vendor/bin/phpstan analyse",
         "test": "vendor/bin/pest",
         "test-coverage": "vendor/bin/pest --coverage",
-        "format": "vendor/bin/pint"
+        "format": "vendor/bin/pint",
+        "docs:install": "wget https://phpdoc.org/phpDocumentor.phar && mv phpDocumentor.phar phpdoc",
+        "docs": "@php phpdoc run --validate -v"
     },
     "config": {
         "sort-packages": true,

docs/getting-started/index.rst

@@ -0,0 +1,23 @@
+.. meta::
+   :layout: landingpage
+
+.. toctree::
+   :hidden:
+   :titlesonly:
+
+   installation
+   usage
+   plugins
+
+Getting Started
+===============
+
+Welcome to the documentation of laravel-audit.
+
+This package provides simple endpoints that provide information and checks about the environment of the application.
+Based on `Hexafuchs/laminas-security <https://github.com/Hexafuchs/laminas-security>`_ and the
+`OWASP Cheat Sheet <https://cheatsheetseries.owasp.org/cheatsheets/PHP_Configuration_Cheat_Sheet.html>`_.
+
+Please feel free to debate existing checks and propose new ones. Security is a complex and evolving topic and many
+people have better insight into this topic than us. Our focus was to create a framework that others can easily expand both
+through the original code as well as through new packages that can register their own checks.

docs/getting-started/installation.rst

@@ -0,0 +1,14 @@
+Installation
+============
+
+You can install the package via composer:
+
+.. code-block:: bash
+
+    composer require hexafuchs/laravel-audit
+
+You can publish the config file with:
+
+.. code-block:: bash
+
+    php artisan vendor:publish --tag="audit-config"

docs/getting-started/plugins.rst

@@ -0,0 +1,12 @@
+Plugins
+=======
+
+If you want to create your own checks instead of working on the original repo, you can simple let your checks implement
+the :php:interface:`\Hexafuchs\Audit\Checks\Checkable` interface or extend the abstract
+:php:class:`\Hexafuchs\Audit\Checks\Check` class (which implements the
+:php:interface:`\Hexafuchs\Audit\Checks\Checkable` interface, but might not be suitable for every use case), then merge
+your checks into the audit.checks config array.
+
+You can also not implement the interface if you want to have another return type, all checks in audit.checks that
+contain an execute function will be executed with no arguments. Note that you will not be able to have colored output
+in the artisan command for other status values.

docs/getting-started/usage.rst

@@ -0,0 +1,16 @@
+Usage
+=====
+
+To gather the results of the checks, make a call to `/api/route`. The result is an array of all checks, with their name,
+group, status and some description for non-successful checks. Checks can result in a success (which is fine), an info
+(which might depend on your situation), a warning (which is likely problematic) or a fatal (which is almost always
+unwanted).
+
+You can configure the checks and some behaviour in the `config/audit.php` after publishing the config file. You should
+most probably add a middleware to restrict the access to the route.
+
+You can also use artisan. Note that this is only really useful for testing or if you have the same php configuration
+for the CLI and the webserver which if you are not sure is probably not the case. It is advised to always check this
+result against the result of `/api/route`. To execute the command, execute `php artisan audit`. You can pass group
+names as arguments to only execute these groups. The exit code is `1` if and only if a non-successful check was
+executed. You can also exclude check states, to list the available options execute the `--help` option.

docs/index.rst

@@ -0,0 +1,11 @@
+.. meta::
+   :layout: landingpage
+
+.. toctree::
+   :hidden:
+   :titlesonly:
+
+   getting-started/index
+
+laravel-audit
+=============

phpdoc.dist.xml

@@ -0,0 +1,30 @@
+<?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>laravel-audit</title>
+    <paths>
+        <output>docs/build</output>
+    </paths>
+    <version number="3.0.0">
+        <folder>latest</folder>
+        <api>
+            <source dsn=".">
+                <path>src</path>
+            </source>
+            <output>api</output>
+            <extensions>
+                <extension>php</extension>
+            </extensions>
+        </api>
+        <guide>
+            <source dsn=".">
+                <path>docs</path>
+            </source>
+            <output>/guide</output>
+        </guide>
+    </version>
+    <setting name="guides.enabled" value="true"/>
+</phpdocumentor>