Merge pull request #27 from eadwinCode/quick_start_doc

Quick-Start Doc

Author: eadwinCode

.github/workflows/publish.yml

@@ -23,3 +23,5 @@ jobs:
           FLIT_USERNAME: ${{ secrets.FLIT_USERNAME }}
           FLIT_PASSWORD: ${{ secrets.FLIT_PASSWORD }}
         run: flit publish
+      - name: Deploy Documentation
+        run: make doc-deploy

.github/workflows/test.yml

@@ -20,6 +20,6 @@ jobs:
       - name: Install Dependencies
         run: flit install --symlink
       - name: Test
-        run: pytest --cov=ellar --cov-report=xml tests
+        run: make test-cov
       - name: Coverage
         uses: codecov/codecov-action@v3.1.1

README.md

@@ -33,79 +33,226 @@
 - Injector
 
 ## Installation
-
+### Poetry Installation
+For [Poetry](https://python-poetry.org/) usages
+```shell
+poetry add ellar
 ```
+
+### Pip Installation
+For normal pip installation
+```shell
 pip install ellar
 ```
 
-## Usage
+## Create a project
+To create an ellar project, you need to have a `pyproject.toml` available on your root directory.
+This is necessary for ellar to store some `metadata` about your project. 
+
+### Step 1
+For Pip Users, you need to create `pyproject.toml` file
+```shell
+touch pyproject.toml
+```
+If you are using `Poetry`, you are ready to go
+
+### Step 2
+Run the ellar create project cli command,
+```shell
+ellar create-project carsite
+```
+
+## Run your project
+Ellar runs [UVICORN - ASGI Server](https://www.uvicorn.org/) under the hood.
+```shell
+ellar runserver --reload
+```
+`--reload` is to watch for file changes
+
+Now go to [http://127.0.0.1:8000](http://127.0.0.1:8000)
+![Swagger UI](docs/img/ellar_framework.png)
+
+
+## Create a project module
+A project module is a project app defining a group of controllers or services including templates and static files.
+So, now we have a project created, lets add an app to the project.
+```shell
+ellar create-module car
+```
+
+## Add Schema
+In `car.schema.py`, lets add some serializer for car input and output data
+```python
+from ellar.serializer import Serializer
+
+class CarSerializer(Serializer):
+    name: str
+    model: str
+    brand: str
+
+
+class RetrieveCarSerializer(CarSerializer):
+    pk: str
+```
 
-Create a file `controller.py`:
+## Add Services
+In `car.services.py`, lets create a dummy repository `CarDummyDB` to manage our car data.
+```python
+import typing as t
+import uuid
+from ellar.di import injectable, singleton_scope
 
-```Python
-from ellar.common import ModuleRouter, Controller, get
 
-router = ModuleRouter('', tag='Math')
+@injectable(scope=singleton_scope)
+class CarDummyDB:
+    class CarDummyDBItem:
+        pk: str
 
+        def __init__(self, **data: t.Dict) -> None:
+            self.__dict__ = data
 
-@router.get("/add")
-def add(request, a: int, b: int):
-    return {"result": a + b}
+        def __eq__(self, other):
+            if isinstance(other, CarDummyDB.CarDummyDBItem):
+                return self.pk == other.pk
+            return self.pk == str(other)
 
+    def __init__(self) -> None:
+        self._data: t.List[CarDummyDB.CarDummyDBItem] = []
 
-@Controller("", tag='Math')
-class MathAPI:
+    def add_car(self, data: t.Dict) -> str:
+        pk = uuid.uuid4()
+        _data = dict(data)
+        _data.update(pk=str(pk))
+        item = self.CarDummyDBItem(**_data)
+        self._data.append(item)
+        return item.pk
 
-    @get('/subtract', )
-    def subtract(self, a: int, b: int):
-        """Subtracts a from b"""
-        return {"result": a - b}
+    def list(self) -> t.List["CarDummyDB.CarDummyDBItem"]:
+        return self._data
 
-    @get('/divide', )
-    def divide(self, a: int, b: int):
-        """Divides a by b"""
-        return {"result": a / b}
+    def update(self, car_id: str, data: t.Dict) -> t.Optional["CarDummyDB.CarDummyDBItem"]:
+        idx = self._data.index(car_id)
+        if idx >= 0:
+            _data = dict(data)
+            _data.update(pk=str(car_id))
+            self._data[idx] = self.CarDummyDBItem(**_data)
+            return self._data[idx]
 
-    @get('/multiple', )
-    def multiple(self, a: int, b: int):
-        """Multiples a with b"""
-        return {"result": a * b}
+    def get(self, car_id: str) -> t.Optional["CarDummyDB.CarDummyDBItem"]:
+        idx = self._data.index(car_id)
+        if idx >= 0:
+            return self._data[idx]
 
+    def remove(self, car_id: str) -> t.Optional["CarDummyDB.CarDummyDBItem"]:
+        idx = self._data.index(car_id)
+        if idx >= 0:
+            return self._data.pop(idx)
 ```
+## Add Controller
+In `car.controllers.py`, lets create `CarController`
 
-Create another file `server.py`:
+```python
+import typing as t
+from ellar.common import Controller, delete, get, put, post
+from ellar.core import ControllerBase
+from ellar.exceptions import NotFound
+from .schemas import CarSerializer, RetrieveCarSerializer
+from .services import CarDummyDB
 
-```Python
-from ellar.core import AppFactory
-from ellar.openapi import OpenAPIDocumentBuilder, OpenAPIDocumentModule
-from .controller import router, MathAPI
 
+@Controller
+class CarController(ControllerBase):
+    def __init__(self, db: CarDummyDB) -> None:
+        self.car_db = db
 
-app = AppFactory.create_app(routers=(router, ), controllers=(MathAPI, ))
+    @post("/create", response={200: str})
+    async def create_cat(self, payload: CarSerializer):
+        pk = self.car_db.add_car(payload.dict())
+        return pk
 
-document_builder = OpenAPIDocumentBuilder()
-document_builder.set_title('Your Title')\
-    .set_version('1.0.2')\
-    .set_contact(name='Eadwin', url='https://www.yahoo.com', email='eadwin@gmail.com')\
-    .set_license('MIT Licence', url='https://www.google.com')
+    @put("/{car_id:str}", response={200: RetrieveCarSerializer})
+    async def update_cat(self, car_id: str, payload: CarSerializer):
+        car = self.car_db.update(car_id, payload.dict())
+        if not car:
+            raise NotFound("Item not found")
+        return car
+
+    @get("/{car_id:str}", response={200: RetrieveCarSerializer})
+    async def get_car_by_id(self, car_id: str):
+        car = self.car_db.get(car_id)
+        if not car:
+            raise NotFound('Item not found.')
+        return car
+
+    @delete("/{car_id:str}", response={204: dict})
+    async def deleted_cat(self, car_id: str):
+        car = self.car_db.remove(car_id)
+        if not car:
+            raise NotFound('Item not found.')
+        return 204, {}
+
+    @get("/", response={200: t.List[RetrieveCarSerializer]})
+    async def list(self):
+        return self.car_db.list()
 
-document = document_builder.build_document(app)
-module = app.install_module(OpenAPIDocumentModule, document=document)
-module.setup_swagger_doc()
 ```
+## Register Service and Controller
+In `car.module.py`, lets register `CarController` and `CarDummyDB`
+
+```python
+from ellar.common import Module
+from ellar.core import ModuleBase
+from ellar.di import Container
+
+from .controllers import CarController
+from .services import CarDummyDB
 
-### Start up Server
-```bash
-uvicorn server:app --reload
+
+@Module(
+    controllers=[CarController],
+    providers=[CarDummyDB],
+    routers=[],
+)
+class CarModule(ModuleBase):
+    def register_providers(self, container: Container) -> None:
+        # for more complicated provider registrations
+        # container.register_instance(...)
+        pass
 ```
 
-### Interactive API docs
 
-Now go to <a href="http://localhost:8000/docs/" target="_blank">http://localhost:8000/docs/</a>
+## Enabling OpenAPI Docs
+To start up openapi, we need to go back to project folder in the `carsite.server.py`
+then add the following below.
+```python
+import os
+
+from ellar.constants import ELLAR_CONFIG_MODULE
+from ellar.core.factory import AppFactory
+from ellar.openapi import OpenAPIDocumentModule, OpenAPIDocumentBuilder
+from .root_module import ApplicationModule
+
+application = AppFactory.create_from_app_module(
+    ApplicationModule,
+    config_module=os.environ.get(
+        ELLAR_CONFIG_MODULE, "carsite.config:DevelopmentConfig"
+    ),
+)
+
+document_builder = OpenAPIDocumentBuilder()
+document_builder.set_title('CarSite API') \
+    .set_version('1.0.0') \
+    .set_contact(name='Eadwin', url='https://www.yahoo.com', email='eadwin@gmail.com') \
+    .set_license('MIT Licence', url='https://www.google.com')
 
-You will see the automatic interactive API documentation (provided by <a href="https://github.com/swagger-api/swagger-ui" target="_blank">Swagger UI</a>):
+document = document_builder.build_document(application)
+module = application.install_module(OpenAPIDocumentModule, document=document)
+module.setup_swagger_doc()
+```
 
-![Swagger UI](docs/img/ellar_demo.gif)
+Now we can test our API at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs#/)
+Please ensure your server is running
+![Swagger UI](docs/img/car_api.png)
 
 ## Status
 Project is still in development