Skip to content

Latest commit

 

History

History
82 lines (57 loc) · 2.94 KB

Docs.md

File metadata and controls

82 lines (57 loc) · 2.94 KB
Raw

Documentation

The documentation in the docs/out directory is generated by running the DocGenerator script. To execute the DocGenerator, run the following composer command:

composer run-script docs-generator

If you make changes to the docs (docs/src/resources), be sure to run the DocGenerator and commit the generated output files.

The Generator will take the template-docs (docs/src/ressources) and transform the code samples to real code for the documentation. There are two types of code samples:

  1. Templates to include Unit-Test (see Template-Snippets)
  2. Code examples that are executed (see PHP-Snippets)

Template-Snippets

With the template-snippets, code from unit-tests can be included. This has the main advantage that this code also extends and improves the unit-test suite. The Github CI executes these unit-tests and ensures that they are working code. To include a unit-test code-sample, use this template syntax:

{{ \CTApi\Test\Unit\Docs\EventRequestTest.testEventRequestDocExample }}

The Doc-Generator takes the unit-test code and transforms the assertEquals statements to more readable code. All Unit-Test for the documentation are stored in the directory tests/unit/docs/. For example, the already mentioned unit-test testEventRequestDocExample has this assert-statement:

$this->assertEquals(21, $christmasService->getId());

This is transformed by the doc-generator to a more readable code:

var_dump( $christmasService->getId());
// Output: 21
  • ⚠ Only use assertEquals statements as other assertions won't be transformed.
  • ⚠ Do not use assert statements inside a loop or if/switch statement.
  • ⚠ Only use simple values like string, integer, and boolean as assert parameters, not objects or arrays.

PHP-Snippets (Deprecated)

⚠ It is not recommended to use PHP-Snippets for new documentation because they are not included in the unit-test suite and are therefore not tested by the CI-Pipeline.

PHP-Snippets are used in docs/src/ressources/CTConfig.md. The code examples are executed by the doc-generator and the content of variables can be displayed to the user using the dd function.

This example Code-Snippet...

$a = 2 + 2;
dd($a);

...will be transfered to this Doc:

$a = 2 + 2;
echo ($a);
// OUTPUT: 4

The Doc-Generator replaces the "dd" function call with an "echo" call to display the content of a variable. ⚠ However, it is not permitted to use the dd(...) method in any kind of loop or if/switch-statement.

Execution Enviroment

The Generator-Script creates the CTClientMock environment which redirects all HTTP calls to the JSON files located in the tests/unit/HttpMock/data directory.

Github-Action

The GitHub Action for the doc-generator runs the DocGenerator and checks for any uncommitted changes. If there are any, the Action will fail. To resolve this, run the DocGenerator locally and commit all the generated doc files.