Guard Documentation in progress

Author: eadwinCode

docs/basics/execution-context.md

@@ -286,26 +286,4 @@ class DogsController(ControllerBase):
         return result
 ```
 
-Also, since `RoleGuard` depends on `Reflector`, it has to be registered as a provider. And we do that in `DogsModule`:
-
-```python
-# project_name/apps/dogs/module.py
-
-from ellar.common import Module
-from ellar.core import ModuleBase
-from ellar.di import Container
-
-from .controllers import DogsController
-from .guards import RoleGuard
-
-
-@Module(
-    controllers=[DogsController],
-    providers=[RoleGuard],
-)
-class DogsModule(ModuleBase):
-    def register_providers(self, container: Container) -> None:
-        # for more complicated provider registrations
-        # container.register_instance(...)
-        pass
-```
+Also, since `RoleGuard` is marked as `injectable`, EllarInjector service will be able to resolve `RoleGuard` without `RoleGuard` registered as a provider.

docs/handling-response/response.md

@@ -203,5 +203,3 @@ class ItemsController(ControllerBase):
     def me(self):
         return PlainTextResponse("some text response.", status_code=200)
 ```
-
-## using serialize_object function

docs/index.md

@@ -15,21 +15,32 @@
 Ellar is a lightweight ASGI framework for building efficient and scalable server-side python applications.
 It supports both OOP (Object-Oriented Programming) and FP (Functional Programming)
 
-
-Ellar is built around [Starlette (ASGI toolkit)](https://www.starlette.io/) which processes all the HTTP requests and background tasks. Although, there is a high level 
-of abstraction, some concepts of Starlette are still supported.
+Ellar is based on [Starlette (ASGI toolkit)](https://www.starlette.io/), a lightweight ASGI framework/toolkit well-suited for developing asynchronous web services in Python. 
+And while Ellar provides a high level of abstraction on top of Starlette, it still incorporates some of its features, as well as those of FastAPI. 
+If you are familiar with these frameworks, you will find it easy to understand and use Ellar.
 
 ## Inspiration
-Ellar was heavily inspired by [NestJS](https://docs.nestjs.com/) in its simplicity in usage while managing complex project structures and applications. 
-It also adopted some concepts of [FastAPI](https://fastapi.tiangolo.com/) in handling request parameters and data serialization with pydantic.
-With that said, the aim of Ellar focuses on a high level of abstraction of framework APIs, project structures, architectures, and speed of handling requests.
+Ellar was deeply influenced by [NestJS](https://docs.nestjs.com/) for its ease of use and ability to handle complex project structures and applications. 
+Additionally, it took some concepts from [FastAPI](https://fastapi.tiangolo.com/) in terms of request parameter handling and data serialization with Pydantic. 
+
+With that said, the objective of Ellar is to offer a high level of abstraction in its framework APIs, along with a well-structured project setup, an object-oriented approach to web application design, 
+the ability to adapt to any desired software architecture, and ultimately, speedy request handling.
 
 ## Installation
 To get started, you need to scaffold a project using [Ellar-CLI](https://eadwincode.github.io/ellar-cli/) toolkit. This is recommended for a first-time user.
 The scaffolded project is more like a guide to project setup.
 
 ```shell
 $(venv) pip install ellar[standard]
+```
+OR
+```shell
+$(venv) pip install ellar ellar-cli
+```
+
+After that, lets create a new project. 
+Run the command below and change the `project-name` with whatever name you decide.
+```shell
 $(venv) ellar new project-name
 ```
 
@@ -60,7 +71,7 @@ Open your browser and navigate to [`http://localhost:8000/`](http://localhost:80
 - `CORS, GZip, Static Files, Streaming responses`
 
 ## Dependency Summary
-- `Python >= 3.6`
+- `Python >= 3.7`
 - `Starlette`
 - `Pydantic`
 - `Injector`

docs/overview/custom_decorators.md

@@ -1,5 +1,6 @@
 
 Ellar provides a variety of function decorators in the `ellar.common` python module that can be used to modify the behavior of route functions. 
+
 These decorators can be used to change the response type of a route function, add filters to the response schema, define the OPENAPI context, and more. 
 In general, these decorators can help to simplify and streamline the process of creating routes.
 
@@ -57,12 +58,14 @@ async def on_connect(self, websocket: WebSocket, code: int):
 ## **Non Route Function Parameters Decorators**
 We discussed decorators that are used to define route function parameter dependencies in Ellar. 
 These decorators, such as `Query`, `Form`, and `Body`, etc. are pydantic models used to specify the expected parameters for a route function. 
+
 However, there are also some route parameters that are **system** dependent, such as the `request` or `websocket` object, and the `response` object. 
 These parameters are resolved by the application and supplied to the route function when needed, and are not specified with pydantic models or user input.
 
 ### Provide(Type)
 The **Provide(Type)** decorator is used to resolve a service provider and inject it into a route function parameter. 
 This can be useful when using the ModuleRouter feature in Ellar. 
+
 It allows for easy injection of services into route functions, making it easier to manage dependencies and improve code organization. 
 This can be useful for resolving database connections, external APIs, or other resources that are used by the route function.
 
@@ -108,6 +111,7 @@ def example_endpoint(ctx = Context()):
 
 In this example, the example_endpoint function is decorated with the **Context()** decorator, which injects the current `IExecutionContext` object into the `ctx` parameter of the function. 
 The `IExecutionContext` object provides access to various resources and information related to the current execution context, such as the current HTTP connection, query parameters, and more. 
+
 In this example, the `switch_to_http_connection()` method is used to access the current HTTP connection and the `get_client()` method is used to get the client object for the connection. 
 The `query_params` attribute of the client object is then accessed and included in the response returned by the endpoint.
 
@@ -167,14 +171,11 @@ async def example_endpoint(ws = Ws()):
 The above code creates a WebSocket route '/test-ws' and when a client connects to this route, 
 the `example_endpoint` function is executed. The `Ws` decorator injects the current `WebSocket` object to the `ws` parameter of the function, which can then be used to interact with the WebSocket connection, such as accepting the connection and sending data to the client.
 
-### Host
-**Host()** decorator injects current client host address to route function parameter.
-
-### Session
-**Session()** decorator injects current Session object to route function parameter.
+The same conditions and examples applies for:
 
-### Http
-**Http()** decorator injects current HTTP connection object to route function parameter.
+- **Host()** decorator injects current client host address to route function parameter.
+- **Session()** decorator injects current Session object to route function parameter. This requires [SessionMiddleware](https://www.starlette.io/middleware/#sessionmiddleware) module from Starlette added in application middleware and also `SessionMiddleware` module depends on [itsdangerous](https://pypi.org/project/itsdangerous/) package.
+- **Http()** decorator injects current HTTP connection object to route function parameter.
 
 ## **Creating a Custom Parameter Decorators**
 You can still create your own route parameter decorators that suits your need. You simply need to follow a contract, `NonParameterResolver`, and override the resolve function.
@@ -203,6 +204,7 @@ class UserParam(NonParameterResolver):
 
 This example defines a custom decorator called `UserParam` that inherits from `NonParameterResolver`. 
 The `resolve` method is overridden to extract the user from the current `IExecutionContext`'s request. 
+
 If the user is found, it is returned as a dict with the key as the `parameter_name` of the decorator, along with an empty list of errors. 
 If no user is found, an empty dict and a list of errors containing an ErrorWrapper object is returned. 
 
@@ -234,6 +236,7 @@ def index(self):
 
 In the example, the index function is decorated with the `render` decorator, 
 which will return a 200 status code and HTML content from my_template. 
+
 The return object from the index function will be used as the templating context for `my_template` during the template rendering process. 
 This allows the function to pass data to the template and have it rendered with the provided context, the rendered template will be the response body.
 
@@ -379,6 +382,7 @@ See [Pydantic Model Export](https://docs.pydantic.dev/usage/exporting_models/#mo
 ### VERSION
 **@version()**  is a decorator that provides endpoint versioning for a route function. 
 This decorator allows you to specify the version of the endpoint that the function is associated with. 
+
 Based on the versioning scheme configuration in the application, versioned route functions are called. This can be useful for maintaining backward compatibility, or for rolling out new features to different versions of an application. 
 More information on how to use this decorator can be found in the [Versioning documentation]()
 
@@ -397,10 +401,12 @@ This indicates that the `get_item_v2_v3` route function will handle version 2 an
 This allows for multiple versions of the same endpoint to be handled by different route functions, each with their own logic and implementation.
 
 ### GUARDS
-**@guards()**  is a decorator that applies a protection class of type GuardCanActivate to a route function. 
-These protection classes have a can_execute function that is called to determine whether a route function should be executed. 
-This decorator allows you to apply certain conditions or checks before a route function is executed, such as authentication or authorization checks. 
+**@guards()**  is a decorator that applies a protection class of type `GuardCanActivate` to a route function. 
+These protection classes have a `can_execute` function that is called to determine whether a route function should be executed. 
+
+This decorator allows you to apply certain conditions or checks before a route function is executed, such as `authentication` or `authorization` checks. 
 This can help to ensure that only authorized users can access certain resources. 
+
 More information on how to use this decorator can be found in the [Guard Documentation]()
 
 A quick example on how to use `guards` decorator:
@@ -425,8 +431,10 @@ async def get_guarded_items(self):
 ```
 The `guards` decorator, like the `version` decorator, takes a list of values as an argument. 
 During a request, the provided guards are called in the order in which they are provided. 
+
 This allows you to apply multiple guards to a single route function and have them executed in a specific order. 
 This is useful for applying multiple levels of security or access control to a single endpoint. 
+
 Each guard class has a `can_execute` function that is called in the order specified by the decorator, if any of the guard's `can_execute` function returns False, the route function will not be executed.
 
 ## **Command Decorators**

docs/templating/templating.md

@@ -73,10 +73,10 @@ This example also shows manual setup of using `jinja2` in Ellar.
 
 ## **Jinja2 usage in Ellar**
 
-In Ellar, we use the `@render` decorator to convert the responses returned by the view to a Templated Response by creating an `HTMLResponseModel` with a status code of 200 to handle the response.
-Also, each registered `Module` is a `TemplateLoader` for loading templates available at `templates_folder`. And, a `Module` TemplateLoader object is created when the `template_folder` folder exists.
+In Ellar, the `@render` decorator transforms the route handler response into a Templated Response via an `HTMLResponseModel` with a status code of 200. 
+And the route handler is required to return a `dictionary` object which serves as the template's context.
 
-When using the `@render` decorator on a route handler, the function is expected to return a `dictionary` object which will be used as a template `context` to be generated.
+Additionally, each registered `Module` functions as a jinja2 `TemplateLoader` for loading templates, but only when a templates_folder is provided and exists.
 
 ### In Controller
 
@@ -359,4 +359,4 @@ This allows for greater control and readability when reversing URLs, and makes i
 
 
 ### Adding template filters and template globals.
-Jinja template filter and global functions can be defined at module level as shown here: [Module Templating Filters](../overview/modules/#module-templating-filters)
+Jinja template filter and global functions can be defined at module level as shown here: [Module Templating Filters](/ellar/overview/modules/#module-templating-filters)

mkdocs.yml

@@ -88,7 +88,7 @@ nav:
   - Caching: caching.md
   - Rate Limiting: throttling.md
 #  - Injection Scopes: basics/injection-scope.md
-#  - Model View Controller: basics/model-view-controller.md
+  - Execution Context: basics/execution-context.md
 #  - Events: basics/events.md
   - Commands:
     - Introduction: commands/index.md