Add documentation and setup files for IoP (Interoperability On Python)

Author: grongierisc

.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+# This is a basic workflow to help you get started with Actions
+
+name: Docs
+
+# Controls when the workflow will run
+on:
+  # Triggers the workflow on push or pull request events but only for the master branch
+  push:
+    branches: [ master ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  # This workflow contains a single job called "build"
+  build:
+    # The type of runner that the job will run on
+    runs-on: ubuntu-latest
+
+    # Steps represent a sequence of tasks that will be executed as part of the job
+    steps:
+      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v2
+      - run: pip install --upgrade pip && pip install mkdocs mkdocs-gen-files
+      - run: git config user.name 'github-actions[bot]' && git config user.email 'github-actions[bot]@users.noreply.github.com'
+      - name: Publish docs
+        run: mkdocs gh-deploy

docs/command-line.md

@@ -0,0 +1,264 @@
+# Command line
+
+Since version 2.3.1, you can use the command line to register your components and productions.
+
+To use it, you have to use the following command :
+```bash
+iop 
+```
+
+output :
+```bash
+usage: python3 -m iop [-h] [-d DEFAULT] [-l] [-s START] [-k] [-S] [-r] [-M MIGRATE] [-e EXPORT] [-x] [-v] [-L]
+optional arguments:
+  -h, --help            display help and default production name
+  -d DEFAULT, --default DEFAULT
+                        set the default production
+  -l, --lists           list productions
+  -s START, --start START
+                        start a production
+  -k, --kill            kill a production (force stop)
+  -S, --stop            stop a production
+  -r, --restart         restart a production
+  -M MIGRATE, --migrate MIGRATE
+                        migrate production and classes with settings file
+  -e EXPORT, --export EXPORT
+                        export a production
+  -x, --status          status a production
+  -v, --version         display version
+  -L, --log             display log
+
+default production: PEX.Production
+```
+
+## help
+
+The help command display the help and the default production name.
+
+```bash
+iop -h
+```
+
+output :
+```bash
+usage: python3 -m iop [-h] [-d DEFAULT] [-l] [-s START] [-k] [-S] [-r] [-M MIGRATE] [-e EXPORT] [-x] [-v] [-L]
+...
+default production: PEX.Production
+```
+
+## default
+
+The default command set the default production.
+
+With no argument, it display the default production.
+
+```bash
+iop -d
+```
+
+output :
+```bash
+default production: PEX.Production
+```
+
+With an argument, it set the default production.
+
+```bash
+iop -d PEX.Production
+```
+
+## lists
+
+The lists command list productions.
+
+```bash
+iop -l
+```
+
+output :
+```bash
+{
+    "PEX.Production": {
+        "Status": "Stopped",
+        "LastStartTime": "2023-05-31 11:13:51.000",
+        "LastStopTime": "2023-05-31 11:13:54.153",
+        "AutoStart": 0
+    }
+}
+```
+
+## start
+
+The start command start a production.
+
+To exit the command, you have to press CTRL+C.
+
+```bash
+iop -s PEX.Production
+```
+
+output :
+```bash
+2021-08-30 15:13:51.000 [PEX.Production] INFO: Starting production
+2021-08-30 15:13:51.000 [PEX.Production] INFO: Starting item Python.FileOperation
+2021-08-30 15:13:51.000 [PEX.Production] INFO: Starting item Python.EmailOperation
+...
+```
+
+## kill
+
+The kill command kill a production (force stop).
+
+Kill command is the same as stop command but with a force stop.
+
+Kill command doesn't take an argument because only one production can be running.
+
+```bash
+iop -k 
+```
+
+## stop
+
+The stop command stop a production.
+
+Stop command doesn't take an argument because only one production can be running.
+
+```bash
+iop -S 
+```
+
+## restart
+
+The restart command restart a production.
+
+Restart command doesn't take an argument because only one production can be running.
+
+```bash
+iop -r 
+```
+
+## migrate
+
+The migrate command migrate a production and classes with settings file.
+
+Migrate command must take the absolute path of the settings file.
+
+Settings file must be in the same folder as the python code.
+
+```bash
+iop -M /tmp/settings.py
+```
+
+## export
+
+The export command export a production.
+
+If no argument is given, the export command export the default production.
+
+```bash
+iop -e
+```
+
+If an argument is given, the export command export the production given in argument.
+
+```bash
+iop -e PEX.Production
+```
+
+output :
+```bash
+{
+    "Production": {
+        "@Name": "PEX.Production",
+        "@TestingEnabled": "true",
+        "@LogGeneralTraceEvents": "false",
+        "Description": "",
+        "ActorPoolSize": "2",
+        "Item": [
+            {
+                "@Name": "Python.FileOperation",
+                "@Category": "",
+                "@ClassName": "Python.FileOperation",
+                "@PoolSize": "1",
+                "@Enabled": "true",
+                "@Foreground": "false",
+                "@Comment": "",
+                "@LogTraceEvents": "true",
+                "@Schedule": "",
+                "Setting": [
+                    {
+                        "@Target": "Adapter",
+                        "@Name": "Charset",
+                        "#text": "utf-8"
+                    },
+                    {
+                        "@Target": "Adapter",
+                        "@Name": "FilePath",
+                        "#text": "/irisdev/app/output/"
+                    },
+                    {
+                        "@Target": "Host",
+                        "@Name": "%settings",
+                        "#text": "path=/irisdev/app/output/"
+                    }
+                ]
+            }
+        ]
+    }
+}
+```
+
+## status
+
+The status command status a production.
+
+Status command doesn't take an argument because only one production can be running.
+
+```bash
+iop -x 
+```
+
+output :
+```bash
+{
+    "Production": "PEX.Production",
+    "Status": "stopped"
+}
+```
+
+Status can be :
+- stopped
+- running
+- suspended
+- troubled
+
+## version
+
+The version command display the version.
+
+```bash
+iop -v
+```
+
+output :
+```bash
+2.3.0
+```
+
+## log
+
+The log command display the log.
+
+To exit the command, you have to press CTRL+C.
+
+```bash
+iop -L
+```
+
+output :
+```bash
+2021-08-30 15:13:51.000 [PEX.Production] INFO: Starting production
+2021-08-30 15:13:51.000 [PEX.Production] INFO: Starting item Python.FileOperation
+2021-08-30 15:13:51.000 [PEX.Production] INFO: Starting item Python.EmailOperation
+...
+```

docs/example.md

@@ -0,0 +1,60 @@
+# Example
+
+Add an example of a business operation and messages in Python.
+
+## Business Operation
+
+Here is an example of a business operation in Python:
+
+```python
+from iop import BusinessOperation, Message
+from dataclasses import dataclass
+
+class MyBusinessOperation(BusinessOperation):
+    
+    def on_init(self):
+        # This method is called when the component is becoming active in the production
+        self.log_info("[Python] ...MyBusinessOperation:on_init() is called")
+        return
+
+    def on_teardown(self):
+        # This method is called when the component is becoming inactive in the production
+        self.log_info("[Python] ...MyBusinessOperation:on_teardown() is called")
+        return
+
+    def on_message(self, message_input: 'MyRequest'):
+        # Called from service/process/operation, message is of type MyRequest with property request_string
+        self.log_info("[Python] ...MyBusinessOperation:on_message() is called with message:" + message_input.request_string)
+        response = MyResponse("...MyBusinessOperation:on_message() echos")
+        return response
+
+@dataclass
+class MyRequest(Message):
+    request_string: str = None
+
+@dataclass
+class MyResponse(Message):
+    my_string: str = None
+```
+
+## Register a Component
+
+To register a component, you need to create a setting.py file in the root of your project.
+
+This file will be used to register your classes and productions.
+
+Example of setting.py:
+
+```python
+import bo
+
+CLASSES = {
+    "Python.MyBusinessOperation": bo.MyBusinessOperation
+}
+```
+
+Then you can use the iop command line to register your component:
+
+```bash
+iop --migrate /path/to/your/project/setting.py
+```