docs: updated docs

avara1986 · avara1986 · commit 9fbdd5beead7 · 2020-11-02T13:56:39.000+01:00
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -60,6 +60,16 @@ or in a config.json:
 }
 ```
 
+### 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
+```
+
+## Configuration file structure
+
 This file can contain the following keywords:
 
 ## pyms - services block
@@ -79,7 +89,7 @@ pyms:
     requests: true
 ```
 
-our `ms` object will have an attribute `requests` that is a instance of our service [requests](services.md). 
+our `ms` object will have an attribute `requests` that is a instance of our [service requests](services.md). 
 
 ## pyms - config block
 This section contains all keywords used for general [Flask Configuration Handling](http://flask.pocoo.org/docs/1.0/config/), along 
@@ -166,7 +176,7 @@ spec:
             name: my-microservice-configmap
 ```
 
-See [Routing](routing.md) and [Examples](examples.md) to continue with this tutorial
+See [Routing](routing.md) and [Examples](tutorials/examples.md) to continue with this tutorial
 
 ## Reload configuration without stopping your services
 
diff --git a/docs/contributing/index.md b/docs/contributing/index.md
@@ -2,7 +2,8 @@
 
 ## Branch workflow
 
-**READ BEFORE CREATE A BRANCH OR OPEN A PR/MR**
+!!! warning
+    READ BEFORE CREATE A BRANCH OR OPEN A PR/MR
 
 - We use [Github Glow](https://guides.github.com/introduction/flow/)
   
@@ -23,30 +24,6 @@ source venv/bin/activate
 pip install -e ".[test]"
 ```
 
-Well-written tests and maintaining good test coverage is important to this project. While developing, run new and existing tests with:
-
-```sh
-pytest --cov=pyms --cov=tests tests/
-```
-
-Add the `-s` flag if you have introduced breakpoints into the code for debugging.
-Add the `-v` ("verbose") flag to get more detailed test output. For even more detailed output, use `-vv`.
-Check out the [pytest documentation](https://docs.pytest.org/en/latest/) for more options and test running controls.
-
-PyMS supports several versions of Python3. To make sure that changes do not break compatibility with any of those versions, we use `tox` to create virtualenvs for each Python version and run tests with that version. To run against all Python versions defined in the `tox.ini` config file, just run:
-
-```sh
-tox
-```
-
-If you wish to run against a specific version defined in the `tox.ini` file:
-
-```sh
-tox -e py36
-```
-
-Tox can only use whatever versions of Python are installed on your system. When you create a pull request, Travis will also be running the same tests and report the results, so there is no need for potential contributors to try to install every single version of Python on their own system ahead of time.
-
 ## Pipenv
 
 ### Advantages over plain pip and requirements.txt
@@ -93,6 +70,51 @@ pipenv install --deploy
 pipenv shell
 ```
 
+## Testing
+Well-written tests and maintaining good test coverage is important to this project. While developing, run new and existing tests with:
+
+```sh
+pytest --cov=[project/pyms/...] --cov=tests tests/
+```
+
+Add the `-s` flag if you have introduced breakpoints into the code for debugging.
+Add the `-v` ("verbose") flag to get more detailed test output. For even more detailed output, use `-vv`.
+Check out the [pytest documentation](https://docs.pytest.org/en/latest/) for more options and test running controls.
+
+PyMS supports several versions of Python3. To make sure that changes do not break compatibility with any of those versions, we use `tox` to create virtualenvs for each Python version and run tests with that version. To run against all Python versions defined in the `tox.ini` config file, just run:
+
+```sh
+tox
+```
+
+If you wish to run against a specific version defined in the `tox.ini` file:
+
+```sh
+tox -e py36
+```
+
+Tox can only use whatever versions of Python are installed on your system. When you create a pull request, Travis will also be running the same tests and report the results, so there is no need for potential contributors to try to install every single version of Python on their own system ahead of time.
+
+## Linters
+
+### MyPy
+
+```
+mypy [project/pyms/...]
+```
+
+### Flake8
+
+```
+flake8 [project/pyms/...] --show-source --statistics --statistics
+```
+
+### Pylint
+
+```
+pylint --rcfile=pylintrc [project/pyms/...]
+```
+
 ## Tutorial: Create your own service
 
 See this [tutorial](../tutorial_create_services.md)
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -57,8 +57,7 @@ This command uses [cookiecutter](https://github.com/cookiecutter/cookiecutter) t
 
 ```bash
 pyms startproject
-`
-``
+```
 
 this outputs a lot of options step by step 
 
@@ -86,4 +85,4 @@ When you finish introducing the options, a project will be created in `[project_
 
 ## What's next?
 
-See [Configuration](configuration.md), [Routing](routing.md) and [Examples](examples.md) to continue with this tutorial
+See [Configuration](configuration.md), [Routing](routing.md) and [Examples](tutorials/examples.md) to continue with this tutorial
diff --git a/docs/requirements.txt b/docs/requirements.txt
diff --git a/docs/routing.md b/docs/routing.md
@@ -1,5 +1,6 @@
 # Routing
-With PyMS you can extend the Microservice with [Connexion](https://github.com/zalando/connexion) and [swagger-ui](https://github.com/sveint/flask-swagger-ui).
+With PyMS you can extend the Microservice with [Connexion](https://github.com/zalando/connexion) and 
+[swagger-ui](https://github.com/sveint/flask-swagger-ui).
 
 To use connexion, you must set in your config.yaml this:
 ```yaml
@@ -100,15 +101,15 @@ As an example, say you have an endpoint specified as:
 
 ```yaml
 paths:
-	/foo:
-		get:
-			operationId: api.foo_get
-			parameters:
-				- name: message
-					description: Some message.
-					in: query
-					type: string
-					required: true
+  /foo:
+	get:
+      operationId: api.foo_get
+	  parameters:
+	  - name: message
+		description: Some message.
+		in: query
+		type: string
+		required: true
 ```
 
 And the view function:
diff --git a/docs/scaffold/configuration.md b/docs/scaffold/configuration.md
@@ -1,7 +1,8 @@
 # Configuration
 
-Project configuration is loaded using [PyMS](https://github.com/python-microservices/pyms) package based on yml or json file.
-Some example files are config.yml, config-docker.yml and tests/config-tests.yml or see [PyMS configuration](configuration.md)
+Project configuration is loaded using [PyMS](https://github.com/python-microservices/pyms) package 
+based on yml or json file. Some example files are config.yml, config-docker.yml and tests/config-tests.yml 
+or see [PyMS configuration](../configuration.md)
 
 ## Documentation
 The Microservice create a URL to inspect the Swagger documentation of the api in:
diff --git a/docs/scaffold/quickstart.md b/docs/scaffold/quickstart.md
@@ -1,69 +1,80 @@
 # Installation
 
-Clone the project
+### Clone the repository
 
+```bash
+git clone git@github.com:purwowd/microservices-scaffold.git
+cd microservices-scaffold
 ```
-git clone https://github.com/python-microservices/microservices-scaffold.git
-```
-
-Install your virtualenv
 
-```
+### Install with virtualenv
+```bash
 virtualenv --python=python[3.6|3.7|3.8] venv
 source venv/bin/activate
 pip install -r requirements.txt
 ```
 
-Or install with pipenv
-
-```
+### Install with pipenv
+```bash
 pip install pipenv
 pipenv install
 ```
 
-Run the script
-
-```
+### Install on MacOS
+```bash
+virtualenv -p python3 venv
+source venv/bin/activate
+pip3 install -r requirements.txt
 python manage.py runserver
 ```
 
-## Check the result
+#### Advantages over plain pip and requirements.txt
+[Pipenv](https://pipenv.readthedocs.io/en/latest/) generates two files: a `Pipfile`and a `Pipfile.lock`.
+* `Pipfile`: Is a high level declaration of the dependencies of your project. It can contain "dev" dependencies (usually test related stuff) and "standard" dependencies which are the ones you'll need for your project to function
+* `Pipfile.lock`: Is the "list" of all the dependencies your Pipfile has installed, along with their version and their hashes. This prevents two things: Conflicts between dependencies and installing a malicious module.
 
-Your default endpoint will be in this url:
+For a more in-depth explanation please refer to  the [official documentation](https://pipenv.readthedocs.io/en/latest/).
 
+## Run your python script
+```bash
+python manage.py runserver
 ```
-http://127.0.0.1:5000/template/
+
+## Check the result
+
+Your default endpoints will be in this url:
+```bash
+http://127.0.0.1:5000/films
+http://127.0.0.1:5000/actors
 ```
 
-This URL is setted in your `config.yml`:
+This URL is set in your `config.yml`:
 
 ```yaml
 pyms:
   config:
     DEBUG: false
     TESTING: false
     APP_NAME: Template
-    APPLICATION_ROOT : /template # <!---
+    APPLICATION_ROOT : "" # <!---
 ```
 
-You can acceded to a `swagger ui <https://swagger.io/tools/swagger-ui/>`_ in the next url:
-
-```
-http://127.0.0.1:5000/template/ui/
+You can acceded to a [swagger ui](https://swagger.io/tools/swagger-ui/) in the next url:
+```bash
+http://127.0.0.1:5000/ui/
 ```
 
-This PATH is setted in your `config.yml`:
+This PATH is set in your `config.yml`:
 
 ```yaml
-    pyms:
-      services:
-        swagger:
-          path: "swagger"
-          file: "swagger.yaml"
-          url: "/ui/" # <!---
+pyms:
+  services:
+    swagger:
+      path: "swagger"
+      file: "swagger.yaml"
+      url: "/ui/" # <!---
 ```
 
 ## Template
-You can create your own project from template:
 
-https://github.com/python-microservices/microservices-template
+You can create your own project from template: [github.com/python-microservices/microservices-template](https://github.com/python-microservices/microservices-template)
diff --git a/docs/scaffold/runindocker.md b/docs/scaffold/runindocker.md
@@ -0,0 +1,11 @@
+# Docker
+You can dockerize this microservice with these steps:
+* Create and push the image
+  ```
+  docker build -t films -f Dockerfile .
+  ```
+
+* Run the image:
+  ```
+  docker run -d -p 5000:5000 films
+  ```
diff --git a/docs/services.md b/docs/services.md
@@ -5,7 +5,7 @@ These services are created as an attribute of the [Microservice class](ms_class.
 
 To add a service check the [configuration section](configuration.md).
 
-You can declare a service but activate/deactivate with the keyword `enabled`, like so:
+You can declare a service but **activate/deactivate** with the keyword `enabled`, like so:
 
 ```yaml
 pyms:
@@ -26,14 +26,16 @@ You must install `pyms` with `pip install py-ms[all]` or `pip install py-ms[swag
 
 ### Configuration
 
-The parameters you can add to your config are the folowing:
+The parameters you can add to your config are the following:
 
 * **path:** The relative or absolute route to your swagger yaml file. The default value is the current directory
 * **file:** The name of you swagger yaml file. The default value is `swagger.yaml`
 * **url:** The url where swagger run in your server. The default value is `/ui/`.
 * **project_dir:** Relative path of the project folder to automatic routing, 
 
-see [this link for more info](https://github.com/zalando/connexion#automatic-routing). The default value is `project`.
+See [this link for more info](https://github.com/zalando/connexion#automatic-routing). The default value is `project`.
+
+See [Routing](routing.md) in this documentation to how configure your Swagger.
 
 ### Example
 
diff --git a/docs/template/index.md b/docs/template/index.md
@@ -115,9 +115,6 @@ pyms:
       url: "/ui/" # <!---
 ```
 
-Read more info in the documentation page: 
-https://microservices-scaffold.readthedocs.io/en/latest/
-
 # Docker
 You can dockerize this microservice wit this steps:
 * Create and push the image
diff --git a/docs/tutorials/examples.md b/docs/tutorials/examples.md
diff --git a/docs/tutorials/tutorial_create_services.md b/docs/tutorials/tutorial_create_services.md
@@ -1,6 +1,6 @@
 # Tutorial 2: How To contribute, Create your own service
 
-* First, you must create a file with the name of your service inside of `pyms.flask.service`, for example, 
+First, you must create a file with the name of your service inside of `pyms.flask.service`, for example, 
 "myawesomesrv":
 
 pyms/flask/services/myawesomesrv.py
@@ -16,15 +16,23 @@ class Service(DriverService):
     }
 ```
 
-* Now, you can configure your service from `config.yml`
+Now, you can configure your service from `config.yml`
 ```yaml
 pyms:
-  config:
+  services:
     myawesomesrv:
       myvalue: 5
+      myvalue2: 5
 ```
 
-* Your service will be instanced inside the `ms` object in `flask.current_app` object. For example, with the last config,
+All configuration in myawesomesrv (myvalue, myvalue2) is loaded in `self.config`: `self.config.myvalue` and 
+`self.config.myvalue2`.
+
+When you "call" an attribute of your service, `DriverService` searchs in `self.config`, and `self.config` contains 
+the key-values that you've defined in your config.yaml for this service. Therefore, each key in your config.yaml
+is an attribute of your Service.
+
+Your service will be instanced inside the `ms` object in `flask.current_app` object. For example, with the last config,
 you could print the folowing code:
 
 ```python
diff --git a/docs/tutorials/tutorial_propagate_traces.md b/docs/tutorials/tutorial_propagate_traces.md
diff --git a/docs/tutorials/tutorials.md b/docs/tutorials/tutorials.md
diff --git a/mkdocs.yml b/mkdocs.yml
