diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml new file mode 100644 index 0000000..19777f1 --- /dev/null +++ b/.github/workflows/build-docs.yml @@ -0,0 +1,50 @@ +name: Build documentation + +on: + push: + branches: ["main"] + workflow_dispatch: + +env: + INSTANCE: 'Writerside/in' + ARTIFACT: 'webHelpIN2-all.zip' + DOCKER_VERSION: '241.18775' + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Build docs using Writerside Docker builder + uses: JetBrains/writerside-github-action@v4 + with: + instance: ${{ env.INSTANCE }} + artifact: ${{ env.ARTIFACT }} + docker-version: ${{ env.DOCKER_VERSION }} + + - name: Save artifact with build results + uses: actions/upload-artifact@v4 + with: + name: docs + path: | + artifacts/${{ env.ARTIFACT }} + retention-days: 7 + + test: + needs: build + runs-on: ubuntu-latest + steps: + - name: Download artifacts + uses: actions/download-artifact@v4 + with: + name: docs + path: artifacts + + - name: Test documentation + uses: JetBrains/writerside-checker-action@v1 + with: + instance: ${{ env.INSTANCE }} \ No newline at end of file diff --git a/.idea/.gitignore b/.idea/.gitignore new file mode 100644 index 0000000..26d3352 --- /dev/null +++ b/.idea/.gitignore @@ -0,0 +1,3 @@ +# Default ignored files +/shelf/ +/workspace.xml diff --git a/.idea/commsy-docs.iml b/.idea/commsy-docs.iml new file mode 100644 index 0000000..6102194 --- /dev/null +++ b/.idea/commsy-docs.iml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml new file mode 100644 index 0000000..1a2336f --- /dev/null +++ b/.idea/modules.xml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml new file mode 100644 index 0000000..94a25f7 --- /dev/null +++ b/.idea/vcs.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/Writerside/c.list b/Writerside/c.list new file mode 100644 index 0000000..c4c77a2 --- /dev/null +++ b/Writerside/c.list @@ -0,0 +1,6 @@ + + + + + \ No newline at end of file diff --git a/Writerside/cfg/buildprofiles.xml b/Writerside/cfg/buildprofiles.xml new file mode 100644 index 0000000..332e47b --- /dev/null +++ b/Writerside/cfg/buildprofiles.xml @@ -0,0 +1,13 @@ + + + + + + + + true + + + + diff --git a/Writerside/cfg/glossary.xml b/Writerside/cfg/glossary.xml new file mode 100644 index 0000000..22bec6b --- /dev/null +++ b/Writerside/cfg/glossary.xml @@ -0,0 +1,7 @@ + + + + + Description of what "foo" is. + + \ No newline at end of file diff --git a/Writerside/images/completion_procedure.png b/Writerside/images/completion_procedure.png new file mode 100644 index 0000000..3535a3f Binary files /dev/null and b/Writerside/images/completion_procedure.png differ diff --git a/Writerside/images/completion_procedure_dark.png b/Writerside/images/completion_procedure_dark.png new file mode 100644 index 0000000..a65beb0 Binary files /dev/null and b/Writerside/images/completion_procedure_dark.png differ diff --git a/Writerside/images/convert_table_to_xml.png b/Writerside/images/convert_table_to_xml.png new file mode 100644 index 0000000..2518a64 Binary files /dev/null and b/Writerside/images/convert_table_to_xml.png differ diff --git a/Writerside/images/convert_table_to_xml_dark.png b/Writerside/images/convert_table_to_xml_dark.png new file mode 100644 index 0000000..4716122 Binary files /dev/null and b/Writerside/images/convert_table_to_xml_dark.png differ diff --git a/Writerside/images/new_topic_options.png b/Writerside/images/new_topic_options.png new file mode 100644 index 0000000..bc6abb6 Binary files /dev/null and b/Writerside/images/new_topic_options.png differ diff --git a/Writerside/images/new_topic_options_dark.png b/Writerside/images/new_topic_options_dark.png new file mode 100644 index 0000000..bf3e48d Binary files /dev/null and b/Writerside/images/new_topic_options_dark.png differ diff --git a/Writerside/images/phpstorm_settings_server.png b/Writerside/images/phpstorm_settings_server.png new file mode 100644 index 0000000..9deab67 Binary files /dev/null and b/Writerside/images/phpstorm_settings_server.png differ diff --git a/Writerside/in.tree b/Writerside/in.tree new file mode 100644 index 0000000..62025c4 --- /dev/null +++ b/Writerside/in.tree @@ -0,0 +1,20 @@ + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/Writerside/redirection-rules.xml b/Writerside/redirection-rules.xml new file mode 100644 index 0000000..9d1ea9f --- /dev/null +++ b/Writerside/redirection-rules.xml @@ -0,0 +1,13 @@ + + + + + + Created after removal of "Starter" from Instance Name + starter.html + + \ No newline at end of file diff --git a/Writerside/topics/API.md b/Writerside/topics/API.md new file mode 100644 index 0000000..ca38f44 --- /dev/null +++ b/Writerside/topics/API.md @@ -0,0 +1,3 @@ +# API + +[REST](REST.md) \ No newline at end of file diff --git a/Writerside/topics/Debugging.md b/Writerside/topics/Debugging.md new file mode 100644 index 0000000..2117ef6 --- /dev/null +++ b/Writerside/topics/Debugging.md @@ -0,0 +1,42 @@ +# Debugging with Xdebug and PHPStorm + +## General +If not build for production, debugging capabilities are already build in. + +Use a remote CLI Interpreter in PHPStorm: +Go to Settings -> PHP and click the three dots (...) on the right side of `CLI Interpreter`. Create a new entry `From Docker, ...` with the following parameters: + +- Type: Docker Compose +- Server: Docker +- Configuration files: Select compose.yml and compose.override.yml +- Service: php + +- Lifecycle: Connect to existing container +- General + - PHP executable: Click refresh on the right side, it should update the PHP version and debugger information automatically. + +Go to Settings -> PHP -> Test Frameworks and add a new configuration with type `Codeception by Remote Interpreter`. Select the docker compose interpreter created above. Unter Codeception library hit refresh on the right side. The Codeception version should be filled automatically. + +Go to Settings -> PHP -> Servers and create a new configuration with the following parameters: + +- Server + - Name: commsy + - Host: localhost + - Port: 443 + - Debugger: Xdebug + - Use path mappings: checked + - Absolute path on the server: /var/www/html + +![phpstorm_settings_server](phpstorm_settings_server.png) + +Add the `XDEBUG_SESSION=PHPSTORM` query parameter to the URL of the page you want to debug, or use [other available triggers](https://xdebug.org/docs/step_debug#activate_debugger). + +Alternatively, you can use [the **Xdebug extension**](https://xdebug.org/docs/step_debug#browser-extensions) for your preferred web browser. + +## Debugging the command line + +On command line, you need to tell PHPStorm which [path mapping configuration](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging-cli.html#configure-path-mappings) should be used, set the value of the PHP_IDE_CONFIG environment variable to `serverName=commsy`, where `commsy` is the name of the debug server configured in PHPStorm. + +```console +XDEBUG_SESSION=1 PHP_IDE_CONFIG="serverName=commsy" php bin/console ... +``` \ No newline at end of file diff --git a/Writerside/topics/Developer.md b/Writerside/topics/Developer.md new file mode 100644 index 0000000..f9a3fb8 --- /dev/null +++ b/Writerside/topics/Developer.md @@ -0,0 +1,3 @@ +# Developer + +Start typing here... \ No newline at end of file diff --git a/Writerside/topics/Getting-Started.md b/Writerside/topics/Getting-Started.md new file mode 100644 index 0000000..b28ed62 --- /dev/null +++ b/Writerside/topics/Getting-Started.md @@ -0,0 +1,20 @@ +# Getting started + +## Using docker compose + +CommSy development setup is greatly assisted by using docker for bootstrapping. There is also a Makefile that will +simplify the use of common commands. The Makefile uses Docker Compose V2 (docker compose) syntax. So make sure +it is enabled. + +``` +# Builds the docker images +make build + +# Starts containers with debugging functions +make up + +# Connect to the php fpm container +make sh +``` + +Open your browser at https://localhost \ No newline at end of file diff --git a/Writerside/topics/Home.topic b/Writerside/topics/Home.topic new file mode 100644 index 0000000..b651f45 --- /dev/null +++ b/Writerside/topics/Home.topic @@ -0,0 +1,27 @@ + + + + + + Start + Starting page + + + + + + + + Primary + + + + + Secondary + + + + \ No newline at end of file diff --git a/Writerside/topics/REST.md b/Writerside/topics/REST.md new file mode 100644 index 0000000..7cd528e --- /dev/null +++ b/Writerside/topics/REST.md @@ -0,0 +1,37 @@ +# REST + +## Authentication +The REST-API uses JSON Web Token (JWT) for authentication. This is a JSON-based open standard for creating access +tokens that assert some number of claims. + +For signing you need to create a pair of public and private keys. Choose a random passphrase for key generation and +provide it as an environment variable to CommSy as `JWT_PASSPHRASE`. + +> Creating a pair of keys should be done automatically when the container is started +{style="note"} + +``` + docker compose exec php openssl genpkey -out config/jwt/private.pem -aes256 -algorithm rsa -pkeyopt rsa_keygen_bits:4096 + docker compose exec php openssl pkey -in config/jwt/private.pem -out config/jwt/public.pem -pubout +``` + +## Obtain the token +You can get a token by sending a POST request to the /api/v2/login_check endpoint + +``` + curl -X POST -H "Content-Type: application/json" /api/v2/login_check -d '{"username":"api","password":"secret"}' +``` + +There is currently only one user with full privileges called "api". The password *must* be set as an environment variable `API_SECRET`. + +## Use the token +The JWT must be passed on each request as an authorization header: `Authorization: Bearer {token}`. + +The API endpoint is /api/v2. + +## Documentation +A documentation is automatically generated in the OpenAPI format under /api/v2/doc. + + + +This is the development focused part of the API documentation. If you are looking for how to use it, see /API. \ No newline at end of file diff --git a/Writerside/topics/Running-Tests.md b/Writerside/topics/Running-Tests.md new file mode 100644 index 0000000..b533f5a --- /dev/null +++ b/Writerside/topics/Running-Tests.md @@ -0,0 +1,18 @@ +# Running tests +In CommSy tests are performed by running Codeception, a complete test suite for php. +Different types of tests are preformed. Those are - but not limited to - Unit-, Acceptance- and Functional- Tests. + +Tests are performed in a dedicated environment and database. + +```terminal + # Run all tests + make test + + # Just unit tests + make test c="Unit" +``` + +Running test from within the php container: +```terminal + APP_ENV=test php vendor/bin/codecept run +``` \ No newline at end of file diff --git a/Writerside/topics/User.md b/Writerside/topics/User.md new file mode 100644 index 0000000..27cab0e --- /dev/null +++ b/Writerside/topics/User.md @@ -0,0 +1,3 @@ +# User + +Start typing here... \ No newline at end of file diff --git a/Writerside/v.list b/Writerside/v.list new file mode 100644 index 0000000..2d12cb3 --- /dev/null +++ b/Writerside/v.list @@ -0,0 +1,5 @@ + + + + + diff --git a/Writerside/writerside.cfg b/Writerside/writerside.cfg new file mode 100644 index 0000000..98e1435 --- /dev/null +++ b/Writerside/writerside.cfg @@ -0,0 +1,11 @@ + + + + + + + + + + \ No newline at end of file