Merge pull request #56 from 5pm-HDH/feature/doc-generator

DocGenerator

.github/workflows/changelog.yml

@@ -12,6 +12,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+    - name: Setup PHP8.0
+      uses: shivammathur/setup-php@v2
+      with:
+        php-version: '8.0'
+
     - uses: actions/checkout@v2
 
     - uses: dangoslen/changelog-enforcer@v2

.github/workflows/doc-generator.yml

@@ -0,0 +1,54 @@
+name: Doc-Generator
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Setup PHP8.0
+      uses: shivammathur/setup-php@v2
+      with:
+        php-version: '8.0'
+
+    - uses: actions/checkout@v2
+
+    - name: Validate composer.json and composer.lock
+      run: composer validate --strict
+
+    - name: Cache Composer packages
+      id: composer-cache
+      uses: actions/cache@v2
+      with:
+        path: vendor
+        key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-php-
+
+    - name: Install dependencies
+      if: steps.composer-cache.outputs.cache-hit != 'true'
+      run: composer install --prefer-dist --no-progress
+
+    - name: Composer dump-autoload to load all files
+      run: composer dump-autoload
+
+    - name: Generate Docs
+      run: composer run-script docs-generator
+
+    - name: Check if Docs are already generated
+      uses: tj-actions/verify-changed-files@v8.8
+      id: verify-changed-files
+      with:
+        files: |
+          docs
+
+    - name: Run step only when files change.
+      if: steps.verify-changed-files.outputs.files_changed == 'true'
+      run: |
+        core.setFailed('Inconsistent Docs. Please run DocGenerator and check in changed Files.')

.github/workflows/static-code-analysis.yml

@@ -12,6 +12,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+    - name: Setup PHP8.0
+      uses: shivammathur/setup-php@v2
+      with:
+        php-version: '8.0'
+
     - uses: actions/checkout@v2
 
     - name: Validate composer.json and composer.lock

.github/workflows/unit-tests.yml

@@ -12,6 +12,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+    - name: Setup PHP8.0
+      uses: shivammathur/setup-php@v2
+      with:
+        php-version: '8.0'
+
     - uses: actions/checkout@v2
 
     - name: Validate composer.json and composer.lock

CHANGELOG.md

@@ -18,6 +18,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Refactoring:
   - [introduce namespace to test-suites, update phpunit-configuration](https://github.com/5pm-HDH/churchtools-api/pull/46)
   - [create AbstractRequestBuilder to simplify RequestBuilder implementation](https://github.com/5pm-HDH/churchtools-api/pull/48)
+- DocGeneration
+  - [generate Docs with executable Code-Examples](https://github.com/5pm-HDH/churchtools-api/pull/56)
 
 ### Fixed
 - Error Handling: [reorganize CTExceptions](https://github.com/5pm-HDH/churchtools-api/pull/53)

README.md

@@ -1,5 +1,10 @@
 # Churchtools (CT) API-Client
 
+![example workflow](https://github.com/5pm-HDH/churchtools-api/actions/workflows/unit-tests.yml/badge.svg)
+
+![example workflow](https://github.com/5pm-HDH/churchtools-api/actions/workflows/static-code-analysis.yml/badge.svg)
+
+
 Churchtools API-Client is a php based wrapper of the churchtools api. This api is tested with the churchtools version
 v3.71.0.
 
@@ -177,6 +182,9 @@ Result:
     </li>
 </ul>
 ```
+## Support / Contribute
+
+Please feel free to Support or Contribute this project.
 
 ### CTLog - Logging Request
 
@@ -216,6 +224,9 @@ Further information on [CTLog-Page](/docs/CTLog.md):
 ### Error-Handling
 The API-Wrapper provides custom exceptions. More on this page: [Error-Handling](/docs/ErrorHandling.md)
 
+### Doc-Generator
+The Doc-Generator processes all Doc-Files and executes the PHP-Code examples to ensure that they are valid. More on this page: [Doc-Generator](/docs/Docs.md)
+
 ## License
 
 This project is licensed under MIT-License feel free to use it or to contribute.

composer.json

@@ -32,6 +32,7 @@
     "test-integration-w": "vendor\\bin\\phpunit.bat --testsuite integration",
     "test-coverage-w": "vendor\\bin\\phpunit.bat --coverage-html .phpunit.cache/coverage-report",
     "psalm": "./vendor/bin/psalm",
-    "psalm-w": "vendor\\bin\\psalm.bat"
+    "psalm-w": "vendor\\bin\\psalm.bat",
+    "docs-generator": "php docs/src/DocGenerator.php"
   }
 }

docs/CTConfig.md

@@ -17,11 +17,10 @@ toplevel-domain no paths are allowed:
 ```php
 use CTApi\CTConfig;
 
-
 $apiUrl = "https://intern.church.tools";
 
-
 CTConfig::setApiUrl($apiUrl);
+
 ```
 
 ## 2. Authentication
@@ -30,35 +29,47 @@ Next you need to authenticate yourself at the api. You can use the `AuthRequest`
 the `CTConfig::authWithCredentials` method:
 
 ```php
+use CTApi\CTConfig;
+
 $email = "someEmail@example.com";
 $password = "1234churchtools";
 
 CTConfig::authWithCredentials($email, $password);
+
 ```
 
 This method will log in to the application to the churchtools api and retrieve the api key. For security reasons the
 CTConfig don't store your email or password. Only the api key will be stored. You can display the api key by using the
 getter method:
 
 ```php
+use CTApi\CTConfig;
+
 $apiToken = CTConfig::getApiKey();
+
 ```
 
 The api key can also be set manually with the setter method:
 
 ```php
+use CTApi\CTConfig;
+
 $apiToken = CTConfig::setApiKey("...");
+
 ```
 
 To validate if the api key is still valid, call the validateApiKey method:
 
 ```php
+use CTApi\CTConfig;
+
 $isValid = CTConfig::validateApiKey();
 if($isValid){
     echo "ApiKey is still valid!";
 }else{
     echo "ApiKey is not valid anymore!";
 }
+
 ```
 
 ## 3. Cache Requests
@@ -76,6 +87,7 @@ CTConfig::disableCache();
 
 // clear stored cache
 CTConfig::clearCache();
+
 ```
 
 By default the cache-files will be stored in the /cache directory. Only `GET`-Requests will be stored in the cache (
@@ -85,12 +97,16 @@ You can disable the cache from single requests by adding the `Cache-Control`-Hea
 Request:
 
 ```php
+$client = new \CTApi\CTClient();
+$userId = 21;
+
 $response = $client->get(
-                '/api/persons/' . $this->userId . '/logintoken',
+                '/api/persons/' . $userId. '/logintoken',
                 [
                     'headers' => [
                         'Cache-Control' => 'no-cache'
                     ]
                 ]
             );
+
 ```

docs/CTLog.md

@@ -30,19 +30,23 @@ CTLog::enableConsoleLog(true);
 // disable log
 CTLog::enableFileLog(false);
 CTLog::enableConsoleLog(false);
+
 ```
 
 ## Set log-level
 
 Only the loglevel of the console-log can be changed:
 
 ```php 
+use CTApi\CTLog;
+
 // reacts to log-levels: ERROR, CRITICAL, ALERT, EMERGENCY
 // is default setting
 CTLog::setConsoleLogLevelError();
 
 // logs all available log-levels: DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY
 CTLog::setConsoleLogLevelDebug();
+
 ```
 
 ## Log messages
@@ -69,6 +73,7 @@ CTLog::getLog()->alert("...");
 
 CTLog::getLog()->emergency("...");
 
+
 ```
 
 ## How Log-levels are used in churchtools-api:

docs/Docs.md

@@ -0,0 +1,40 @@
+# Documentation
+
+The Documentation in the `docs`-Directory are generated by the DocGenerator-Script. The DocGenerator can be executed by composer:
+
+```
+composer run-script docs-generator
+```
+
+The Generator will then execute every PHP-Code example to ensure that they are executable! The Template-Docs are stored in the `docs/src/ressources`-Directory.
+
+
+## Template-Docs
+
+The Doc-Templates are MD-Files contain all the information the Doc should contain. Only the PHP-Code examples are processed by the DocGenerator-Script. This Script executes the Code-Examples and display the result in the generated Doc.
+
+This example Code-Snippet...
+
+```php 
+$a = 2 + 2;
+dd($a);
+```
+
+...will be transfered to this Doc:
+
+```php
+$a = 2 + 2;
+echo ($a);
+// OUTPUT: 4
+```
+
+The Generator converts the "dd"-Function call to an "echo" call. In the next Line it will display the content of the variable $a.
+
+⚠ The `dd(...)`-Method is not allowed in any kind of Loop or If/Switch-Statement.⚠
+
+## Execution Enviroment
+The Generator-Script builds the CTClientMock-Enviroment. All Http calls are redirected to the Json-Files in the `tests/unit/HttpMock/data`-directory.
+
+## Github-Action
+
+If you change something in the template-docs please call the generator-script. The Github-Action "doc-generator" will check if there is any inconsistency between the template-docs and the generated docs.