initial

.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 }}

Writerside/c.list

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE categories
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/categories.dtd">
+<categories>
+    <category id="wrs" name="Writerside documentation" order="1"/>
+</categories>

Writerside/cfg/buildprofiles.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE buildprofiles SYSTEM "https://resources.jetbrains.com/writerside/1.0/build-profiles.dtd">
+<buildprofiles xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-profiles.xsd"
+               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+
+    <variables></variables>
+    <build-profile instance="in">
+        <variables>
+            <noindex-content>true</noindex-content>
+        </variables>
+    </build-profile>
+
+</buildprofiles>

Writerside/cfg/glossary.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE terms SYSTEM "https://resources.jetbrains.com/writerside/1.0/glossary.dtd">
+<terms>
+    <term name="foo">
+        Description of what "foo" is.
+    </term>
+</terms>

Writerside/in.tree

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE instance-profile
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
+
+<instance-profile id="in"
+                 name="Instance Name"
+                 start-page="Home.topic">
+
+    <toc-element topic="Home.topic">
+    </toc-element>
+    <toc-element topic="Developer.md">
+        <toc-element topic="Running-Tests.md"/>
+        <toc-element topic="Getting-Started.md"/>
+        <toc-element topic="Debugging.md"/>
+    </toc-element>
+    <toc-element topic="API.md">
+        <toc-element topic="REST.md"/>
+    </toc-element>
+    <toc-element topic="User.md"/>
+</instance-profile>

Writerside/redirection-rules.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE rules SYSTEM "https://resources.jetbrains.com/writerside/1.0/redirection-rules.dtd">
+<rules>
+    <!-- format is as follows
+    <rule id="<unique id>">
+        <accepts>page.html</accepts>
+    </rule>
+    -->
+    <rule id="265102f0">
+        <description>Created after removal of "Starter" from Instance Name</description>
+        <accepts>starter.html</accepts>
+    </rule>
+</rules>

Writerside/topics/API.md

@@ -0,0 +1,3 @@
+# API
+
+[REST](REST.md)

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 ...
+```

Writerside/topics/Developer.md

@@ -0,0 +1,3 @@
+# Developer
+
+Start typing here...

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

Writerside/topics/Home.topic

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd">
+<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
+       title="Home" id="Home">
+
+    <section-starting-page>
+        <title>Start</title>
+        <description>Starting page</description>
+
+        <spotlight>
+            <a href="Developer.md" type="development"></a>
+            <a href="User.md" type="start"></a>
+        </spotlight>
+
+        <primary>
+            <title>Primary</title>
+            <a href="Developer.md"></a>
+        </primary>
+
+        <secondary>
+            <title>Secondary</title>
+            <a href="User.md"></a>
+        </secondary>
+    </section-starting-page>
+</topic>

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.

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
+```

Writerside/topics/User.md

@@ -0,0 +1,3 @@
+# User
+
+Start typing here...

Writerside/v.list

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE vars SYSTEM "https://resources.jetbrains.com/writerside/1.0/vars.dtd">
+<vars>
+    <var name="product" value="Writerside"/>
+</vars>

Writerside/writerside.cfg

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE ihp SYSTEM "https://resources.jetbrains.com/writerside/1.0/ihp.dtd">
+
+<ihp version="2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+     xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/writerside-cfg.xsd">
+    <topics dir="topics"/>
+    <images dir="images" web-path="images"/>
+    <categories src="c.list"/>
+    <vars src="v.list"/>
+    <instance src="in.tree"/>
+</ihp>