Updated docs

avara1986 · avara1986 · commit 0710acd59c78 · 2019-09-23T18:56:17.000+02:00
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -1,5 +1,12 @@
 # Configuration
 
+## Environments variables of PyMS:
+
+**CONFIGMAP_FILE**: The path to the configuration file. By default, PyMS search the configuration file in your
+actual folder with the name "config.yml"
+**CONFIGMAP_SERVICE**: the name of the keyword that define the block of key-value of [Flask Configuration Handling](http://flask.pocoo.org/docs/1.0/config/)
+and your own configuration (see the next section to more  info)
+
 ## Create configuration
 Each microservice needs a config file in yaml or json format to work with it. This configuration contains
 the Flask settings of your project and the [Services](services.md). With this way to create configuration files, we 
@@ -44,7 +51,6 @@ or in a config.json:
 
 This file could contains this keywords:
 
-
 ## pyms block
 
 ```pyms```: all subsets inside this keyword are the settings of this library. Each keyword will be a service of our
@@ -96,6 +102,8 @@ ms1-api:
   TESTING: false
 ```
 
+You can set this keyword with the environment var **CONFIGMAP_SERVICE**.
+
 ## Import Configuration
 With pyms, all configuration is stored as flask configuration and it can be acceded from:
 
@@ -142,4 +150,37 @@ API = Api(
 ```
 
 **IMPORTANT:** If you use this method to get configuration out of context, you must set the `CONFIGMAP_SERVICE` or set 
-the default key `ms` for your configuration block in your config.yml
+the default key `ms` for your configuration block in your config.yml
+
+
+## Looking for Configuration file with Kubernetes Configmaps
+By default, Microservice class search a config.yml in the same path. You can set a different route or set a json file.
+To change this path, define a environment variable `CONFIGMAP_FILE`.
+
+This way of looking for the configuration is useful when you work with Docker and Kubernetes. For example, you can integrate
+a configmap of Kubernetes, with this microservice and a deployment with:
+
+```yaml
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+  name: my-microservice
+spec:
+  replicas: 1
+  template:
+    spec:
+      containers:
+      - name: my-microservice
+        image: ...
+        env:
+          - name: CONFIGMAP_FILE
+            value: "/usr/share/microservice/config.yaml"
+
+        volumeMounts:
+          - mountPath: /usr/share/microservice
+            name: ms-config-volume
+      volumes:
+        - name: ms-config-volume
+          configMap:
+            name: my-microservice-configmap
+```
diff --git a/docs/index.md b/docs/index.md
@@ -1,7 +1,17 @@
 # Welcome to PyMS
 
-PyMS, Python MicroService, is a collection of libraries, best practices and recommended ways to build 
-microservices with Python.
+PyMS, Python MicroService, is a [Microservice chassis pattern](https://microservices.io/patterns/microservice-chassis.html) 
+like Spring Boot (Java) or Gizmo (Golang). PyMS is a collection of libraries, best practices and recommended ways to build 
+microservices with Python which handles cross-cutting concerns: 
+- Externalized configuration
+- Logging
+- Health checks
+- Metrics (TODO)
+- Distributed tracing
+
+PyMS is powered by [Flask](https://flask.palletsprojects.com/en/1.1.x/), [Connexion](https://github.com/zalando/connexion) and [Opentracing](https://opentracing.io/).
+
+Get started with [Installation](installation.md) and then get an overview with the [Quickstart](quickstart.md). 
 
 ## Motivation
 
@@ -24,9 +34,11 @@ Nowadays, is not perfect and we have a looong roadmap, but we hope this library
 
 
 ## Index:
-* [PyMS structure](structure.md)
+* [Installation](installation.md)
+* [Quickstart](quickstart.md)
 * [Configuration](configuration.md)
 * [Services](services.md)
+* [PyMS structure](structure.md)
 * [Microservice class](ms_class.md)
 * [Quick start and examples](examples.md)
 * [Structure of a microservice project](structure_project.md)
diff --git a/docs/installation.md b/docs/installation.md
@@ -0,0 +1,17 @@
+# Installation
+
+## Python Version
+We recommend using the latest version of Python 3. PyMS supports Python 3.6 and newer and PyPy.
+
+```
+virtualenv --python=python[3.6|3.7|3.8] venv
+source venv/bin/activate
+```
+
+## Install PyMS
+
+```
+pip install py-ms
+```
+
+See [Quickstart](quickstart.md) to continue with this tutorial
diff --git a/docs/ms_class.md b/docs/ms_class.md
@@ -58,38 +58,4 @@ print(ms.config.multiplevars.config2)
 # >> "test2"
 ```
 
-
-
-# Looking for Configuration file
-By default, Microservice class search a config.yml in the same path. You can set a different route or set a json file.
-To change this path, define a environment variable `CONFIGMAP_FILE`.
-
-This way of looking for the configuration is useful when you work with Docker and Kubernetes. For example, you can integrate
-a configmap of Kubernetes, with this microservice and a deployment with:
-
-```yaml
-apiVersion: extensions/v1beta1
-kind: Deployment
-metadata:
-  name: my-microservice
-spec:
-  replicas: 1
-  template:
-    spec:
-      containers:
-      - name: my-microservice
-        image: ...
-        env:
-          - name: CONFIGMAP_FILE
-            value: "/usr/share/microservice/config.yaml"
-
-        volumeMounts:
-          - mountPath: /usr/share/microservice
-            name: ms-config-volume
-      volumes:
-        - name: ms-config-volume
-          configMap:
-            name: my-microservice-configmap
-```
-
 Check more examples in [this Github page](https://github.com/python-microservices/pyms/tree/master/examples)
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -0,0 +1,48 @@
+# Quickstart
+
+This page gives a good introduction to PyMS. It assumes you already have PyMS installed. If you do not, head over to the [Installation](installation.md) section.
+
+You need to create 2 files: main.py and config.yml:
+
+main.py
+```python
+from flask import jsonify
+
+from pyms.flask.app import Microservice
+
+ms = Microservice(path=__file__) # 1.1
+app = ms.create_app() # 2.1
+
+
+@app.route("/") # 3.1
+def example():
+    return jsonify({"main": "hello world"})
+
+
+if __name__ == '__main__':
+    app.run()
+```
+
+config.yml
+```yaml
+pyms: # 1.2
+  requests:
+    data: {}
+ms: # 1.3
+  DEBUG: true
+  APP_NAME: business-glossary
+  APPLICATION_ROOT : ""
+  SECRET_KEY: "gjr39dkjn344_!67#"
+```
+
+So what did that code do?
+1. Create a instance of PyMS Microservice class (#1.1). This initialization inject the configuration defined in the 
+1.3 block and could be accessed through current_app.config. Then, initialize the service defined in the 1.2 block. See [Services](services.md) for more details.
+2. Initialize [Flask](https://flask.palletsprojects.com/en/1.1.x/) instance, [Connexion](https://github.com/zalando/connexion) 
+if it was defined in the pyms configuration block, create a tracer, add health-check blueprint, initialize libs and set the PyMS Microservice in
+`ms` attribute and you can access to it with `current_app.ms`. This steps has their each functions and you can easy override it.
+3. `create_app` return the flask instance and you can interact with it as a typical flask app
+
+
+
+See [Configuration](configuration.md) and [Examples](examples.md) to continue with this tutorial
diff --git a/examples/mininum_microservice/config.yml b/examples/mininum_microservice/config.yml
@@ -1,2 +1,7 @@
 my-minimal-microservice:
-  APP_NAME: "Python Microservice"
+  DEBUG: true
+  TESTING: false
+  SWAGGER: true
+  APP_NAME: business-glossary
+  APPLICATION_ROOT : ""
+  SECRET_KEY: "gjr39dkjn344_!67#"
