PyMS Documentation issues (#1)

* docs: resolved PyMS issue #162

python-microservices/pyms#162

* docs: resolved PyMS issue #161

python-microservices/pyms#161

* docs: updated command line options

Closed issue python-microservices/pyms#203

* docs: added example of jaeger server

Author: avara1986

docs/command_line.md

@@ -90,4 +90,11 @@ This command uses [prance](https://github.com/jfinkhaeuser/prance) to validate t
 pyms merge-swagger --file 'app/swagger/swagger.yaml'
 >>  Swagger file generated [swagger-complete.yaml] 
 >>  OK
+```
+
+### Create configuration from command line
+PyMS has a command line option to create a config file. You can run the next command in the terminal:
+
+```bash
+pyms create-config
 ```

docs/installation.md

@@ -3,11 +3,6 @@
 ## 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
 
 **Installing pyms with all dependencies**
@@ -35,4 +30,61 @@ pip install py-ms[metrics]
 pip install py-ms[trace]
 ```
 
+## Install with virtualenv and requirements.txt
+
+Create a [virtualenv](https://virtualenv.pypa.io/en/latest/)
+
+```
+virtualenv --python=python[3.6|3.7|3.8] venv
+source venv/bin/activate
+```
+
+Add in your requirements.txt:
+
+```
+py-ms[all|metrics|trace]==[VERSION]
+```
+
+In example:
+
+```
+py-ms[all]>=2.7.0
+```
+
+and then install with
+
+```
+pip install -r requirements.txt
+```
+
+## Install with pipenv and Pipfile
+
+Create a [pipenv](https://pipenv-es.readthedocs.io/) environment
+
+```
+pipenv install
+```
+
+Or install PyMS with the command:
+
+```
+pipenv install py-ms[all]>=2.7.0
+```
+
+Or add PyMS in your Pipfile:
+
+```toml
+[[source]]
+name = "pypi"
+url = "https://pypi.org/simple"
+verify_ssl = true
+
+[dev-packages]
+
+[packages]
+py-ms = {extras = ["all"],version = "==2.6.1"}
+```
+
+## Next Steps
+
 See [Quickstart](quickstart.md) to continue with this tutorial

docs/structure_project.md

@@ -6,7 +6,8 @@ You have applied the Microservice architecture pattern. Requests often span mult
 Each service handles a request by performing one or more operations, e.g. database queries, publishes messages, etc.
 
 PyMS injects a unique request ID with [opentracing](https://github.com/opentracing-contrib/python-flask) and
-passes the external request id to all services that are involved in handling the current request with the [service request](services.md)
+passes the external request id to all services that are involved in handling the current request with the
+[service request](services.md)
 
 ## 1. Simple Trace
 
@@ -189,3 +190,24 @@ You can see the flow of these requests in this diagram:
 
 You can check this example on [this Github page](https://github.com/python-microservices/pyms/tree/master/examples/microservice_distribued_tracing)
 
+The simplest way to start the all-in-one is to use the pre-built image published to DockerHub (a single command line).
+
+# Tracer server
+
+You can see the traces with [jaeger server](https://www.jaegertracing.io/docs/1.20/getting-started/):
+
+```shell
+$ docker run -d --name jaeger \
+  -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \
+  -p 5775:5775/udp \
+  -p 6831:6831/udp \
+  -p 6832:6832/udp \
+  -p 5778:5778 \
+  -p 16686:16686 \
+  -p 14268:14268 \
+  -p 14250:14250 \
+  -p 9411:9411 \
+  jaegertracing/all-in-one:1.20
+```
+
+You can then navigate to `http://localhost:16686` to access the Jaeger UI.

docs/tutorials/tutorial_propagate_traces.md

@@ -0,0 +1,79 @@
+# Tutorial 3: Testing with Pytest and PyMS
+
+Testing a microservice with PyMS is very similar to a Flask Application.
+
+## Create App Pattern
+
+The recommended way to start is using [Create App Pattern](https://flask.palletsprojects.com/en/1.1.x/patterns/appfactories/).
+ Using PyMS is like Flask:
+
+```python
+from pyms.flask.app import Microservice
+
+def create_app():
+    ms = Microservice(path=__file__)
+    return ms.create_app()
+```
+
+## Conftest.py and Pytest
+
+Then, you can use these functions in your conftest.py with Pytest:
+
+### Config environment
+
+PyMS needs the environment variable `PYMS_CONFIGMAP_FILE` to look for the configuration file, is recommended
+to create a specific config file to testing:
+
+```python
+import os
+def conf_environment():
+    if not os.environ.get("PYMS_CONFIGMAP_FILE", False):
+        os.environ["PYMS_CONFIGMAP_FILE"] = os.path.join(os.path.dirname(os.path.abspath(__file__)), "config-tests.yml")
+```
+
+### Initialize Flask
+
+Create an app object to use in tests
+
+```python
+import pytest
+@pytest.fixture(scope="session")
+def app():
+    conf_environment()
+    app = create_app()
+    return app
+```
+
+### Initialize Flask
+
+Create Flask testing client
+
+```python
+@pytest.fixture(scope="module")
+def client(app, db):
+    """A test client for the app."""
+    return app.test_client()
+```
+
+### Extra: url of your tests
+
+Get the url to use in tests
+
+```python
+@pytest.fixture(scope="module")
+def base_url(app):
+    """Base url of the service."""
+    return app.config["APPLICATION_ROOT"]()
+```
+
+### Ready to testing your code
+
+With this configuration, you are ready to create your own tests with PyMS:
+
+```python
+def test_list_actors(client, base_url):
+    response = client.get('{base_url}healthcheck'.format(base_url=base_url))
+    assert 200 == response.status_code
+```
+
+As you can see, is very similar to a normal Flask application :)

docs/tutorials/tutorial_testing.md

@@ -11,3 +11,7 @@ With this tutorial you can solve the problem of [distributed tracing](https://mi
 ## Tutorial 2: How To contribute, Create your own service
 
 [See tutorial](tutorial_create_services.md)
+
+## Tutorial 3: Testing with Pytest and PyMS
+
+[See tutorial](tutorial_testing.md)

docs/tutorials/tutorials.md

@@ -15,9 +15,8 @@ nav:
     - Microservice class: ms_class.md
     - Routing: routing.md
     - Encrypt/Decrypt Configuration: encrypt_decryt_configuration.md
-    - Command line: command_line.md
     - PyMS structure: structure.md
-    - Structure of a microservice project: structure_project.md
+    - Command line: command_line.md
   - Introduction to microservices:
       - Introduction to microservices (ENG): microservices.md
       - Introduction to microservices (SPA): microservicios.md
@@ -26,6 +25,7 @@ nav:
       - Basic Examples: tutorials/examples.md
       - Create services: tutorials/tutorial_create_services.md
       - Propagate traces: tutorials/tutorial_propagate_traces.md
+      - Testing with PyMS: tutorials/tutorial_testing.md
   - Projects:
     - Scaffold:
         - Index: scaffold/index.md