docs: add getting started and developer guide document

README.md

@@ -19,3 +19,40 @@
 
 # Python Plugin Runner for Apache APISIX
 
+[![Build Status](https://github.com/apache/apisix-python-plugin-runner/actions/workflows/runner-test.yml/badge.svg?branch=master)](https://github.com/apache/apisix-python-plugin-runner/actions)
+[![Build Status](https://github.com/apache/apisix-python-plugin-runner/actions/workflows/runner-lint.yml/badge.svg?branch=master)](https://github.com/apache/apisix-python-plugin-runner/actions)
+
+Runs [Apache APISIX](http://apisix.apache.org/) plugins written in Python. Implemented as a sidecar that accompanies
+APISIX.
+
+![apisix-plugin-runner-overview](./docs/assets/images/apisix-plugin-runner-overview.png)
+
+# Why apisix-python-plugin-runner
+
+APISIX offers many full-featured plugins covering areas such as authentication, security, traffic control, serverless,
+analytics & monitoring, transformations, logging.
+
+It also provides highly extensible API, allowing common phases to be mounted, and users can use these api to develop
+their own plugins.
+
+APISIX supports writing plugins in multiple languages in
+version [2.7.0](https://github.com/apache/apisix/blob/master/CHANGELOG.md#270), this project is APISIX Python side
+implementation that supports writing plugins in Python.
+
+# Use apisix-python-plugin-runner
+
+For configuration and use, please refer to the [Getting Started](./docs/en/latest/getting-started.md) document.
+
+# Get Involved in Development
+
+Welcome to make contributions, but before you start, please check out
+[Developer Guide](./docs/en/latest/developer-guide.md) to learn how to run and debug `apisix-python-plugin-runner`
+in your own environment.
+
+# Status
+
+This project is currently in the experimental stage and it is not recommended to be used in a production environment.
+
+# License
+
+[Apache 2.0 LICENSE](./LICENSE)

docs/en/latest/developer-guide.md

@@ -0,0 +1,96 @@
+---
+title: Developer Guide
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## Overview
+
+This documentation explains how to develop this project.
+
+
+## Prerequisites
+
+* Python 3.6+
+* APISIX 2.7.0
+
+
+## Debug
+
+- Run `make setup` Installation dependencies
+- Run `export PYTHONPATH=$PYTHONPATH:/path/to/apisix-python-plugin-runner` loading project path 
+- Run `APISIX_LISTEN_ADDRESS=unix:/tmp/runner.sock python3 apisix/main.py start`
+to start it.
+
+
+## Plugin
+
+#### Plugin directory
+```
+/path/to/apisix-python-plugin-runner/apisix/plugin
+```
+the `.py` files in this directory autoload
+
+
+#### Plugin example
+```
+/path/to/apisix-python-plugin-runner/apisix/plugin/say.py
+```
+
+#### Plugin Format
+```python
+from apisix.runner.plugin.base import Base
+from apisix.runner.http.request import Request
+from apisix.runner.http.response import Response
+
+
+class Say(Base):
+    def __init__(self):
+        super(Say, self).__init__(self.__class__.__name__)
+
+    def filter(self, request: Request, response: Response):
+        headers = request.headers
+        headers["X-Resp-A6-Runner"] = "Python"
+        response.body = "Hello, Python Runner of APISIX"
+        response.headers = headers
+```
+- The plugin must inherit the `Base` class
+- The plugin must implement the `filter` function
+- `filter` function parameters can only contain `Request` and `Response` classes as parameters
+- Request parameter can get request information
+- Response parameter can set response information
+- `self.config` can get plug-in configuration information
+
+
+## Test
+
+Run `make test`.
+
+
+## Data Format
+
+[FlatBuffers](https://github.com/google/flatbuffers)
+
+
+## Data Protocol
+
+```
+1 byte of type + 3 bytes of length + data
+```

docs/en/latest/getting-started.md

@@ -0,0 +1,124 @@
+---
+title: Getting started
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## Overview
+This document explains how to use Python Runner
+
+## Prerequisites
+
+* Python 3.6+
+* APISIX 2.7.0
+
+
+## Installation
+
+```bash
+$ git clone https://github.com/apache/apisix-python-plugin-runner.git
+$ cd apisix-python-plugin-runner
+$ make install
+```
+
+## Launch
+
+### Configuration Python Runner
+
+> Development Mode
+
+#### Run APISIX Python Runner
+```bash
+$ cd /path/to/apisix-python-plugin-runner
+$ APISIX_LISTEN_ADDRESS=unix:/tmp/runner.sock python3 apisix/main.py start
+```
+
+#### Modify APISIX configuration file
+```bash
+$ vim /path/to/apisix/conf/config.yaml
+apisix:
+  admin_key:
+    - name: "admin"
+      key: edd1c9f034335f136f87ad84b625c8f1
+      role: admin
+ext-plugin:
+  path_for_test: /tmp/runner.sock
+```
+
+> Production Mode
+
+#### Modify APISIX configuration file
+```bash
+$ vim /path/to/apisix/conf/config.yaml
+apisix:
+  admin_key:
+    - name: "admin"
+      key: edd1c9f034335f136f87ad84b625c8f1
+      role: admin
+ext-plugin:
+  cmd: [ "python3", "/path/to/apache/apisix-python-plugin-runner/apisix/main.py", "start" ]
+```
+
+### Start or Restart APISIX
+```bash
+$ cd /path/to/apisix
+# Start or Restart
+$ ./bin/apisix [ start | restart ]
+```
+
+### Configure APISIX Routing Rule
+```bash
+$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+  "uri": "/get",
+  "plugins": {
+    "ext-plugin-pre-req": {
+      "conf": [
+        { "name": "say", "value":"{\"body\":\"hello\"}"}
+      ]
+    }
+  },
+  "upstream": {
+        "type": "roundrobin",
+        "nodes": {
+            "127.0.0.1:1980": 1
+        }
+    }
+}
+'
+```
+
+
+# Testing
+```bash
+$ curl http://127.0.0.1:9080/get -i
+HTTP/1.1 200 OK
+Date: Fri, 13 Aug 2021 13:39:18 GMT
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+host: 127.0.0.1:9080
+accept: */*
+user-agent: curl/7.64.1
+X-Resp-A6-Runner: Python
+Server: APISIX/2.7
+
+Hello, Python Runner of APISIX
+```