Merge pull request #4 from tarsil/feature/docs

Documentation
tarsil · Mar 17, 2023 · 55d9319 · 55d9319
2 parents d8df23b + a0129fe
commit 55d9319
Show file tree

Hide file tree

Showing 12 changed files with 305 additions and 65 deletions.
diff --git a/README.md b/README.md
@@ -1,11 +1,11 @@
-# Saffier
+# Starlette Bridge
 
 <p align="center">
-  <a href="https://starlette-bridge.tarsild.io"><img src="https://www.starlette.io/img/starlette.png" alt='Saffier'></a>
+  <a href="https://starlette-bridge.tarsild.io"><img width="420px" src="https://www.starlette.io/img/starlette.png" alt='Starlette Bridge'></a>
 </p>
 
 <p align="center">
-    <em>🚀 The Starlette events bridge you need. 🚀</em>
+    <em>🚀 The Starlette events bridge that you need. 🚀</em>
 </p>
 
 <p align="center">
@@ -54,3 +54,128 @@ To install Starlette Bridge, simply run:
 ```shell
 $ pip install starlette-bridge
 ```
+
+## How to use
+
+This is actually very simple to do it. You don't need to do anything particularly difficult, in
+fact, you only need to update where your Starlette object comes from.
+
+```python hl_lines="1"
+from starlette_bridge import Starlette
+
+app = Starlette()
+```
+
+And that is pretty much it.
+
+### How does it work
+
+Starlette bridge simply maps your `on_startup` and `on_shutdown` events and converts them into
+the new `lifespan` async generator from `Starlette`.
+
+This way you can continue to use your preferred way of assembling the events while maintaining
+the new structure required by Starlette for managing events.
+
+### on_event and add_event_handler
+
+These two pieces of functionality are also supported by the bridge making sure that what you had
+in the past, still remains working as is without changing the syntax.
+
+Let us see an example how it works. We will be using [Starlette Bridge](https://saffier.tarsild.io) because
+already contains events we want to use.
+
+#### on_startup/on_shutdown
+
+Using the `on_startup` and `on_shutdown`.
+
+```python hl_lines="3 10-11"
+from saffier import Database, Registry
+
+from starlette_bridge import Starlette
+
+database = Database("sqlite:///db.sqlite")
+models = Registry(database=database)
+
+
+app = Starlette(
+    on_startup=[database.connect],
+    on_shutdown=[database.disconnect],
+)
+```
+
+#### Lifespan
+
+You can, of course, use the lifespan as well.
+
+```python hl_lines="5 20"
+from contextlib import asynccontextmanager
+
+from saffier import Database, Registry
+
+from starlette_bridge import Starlette
+
+database = Database("sqlite:///db.sqlite")
+models = Registry(database=database)
+
+
+@asynccontextmanager
+async def lifespan(app: Starlette):
+    # On startup
+    await database.connect()
+    yield
+    # On shutdown
+    await database.disconnect()
+
+
+app = Starlette(lifespan=lifespan)
+```
+
+#### on_event and add_event_handler
+
+As mentioned before, those two functionalities are also available.
+
+##### on_event
+
+```python hl_lines="3 12 17"
+from saffier import Database, Registry
+
+from starlette_bridge import Starlette
+
+database = Database("sqlite:///db.sqlite")
+models = Registry(database=database)
+
+
+app = Starlette()
+
+
+@app.on_event("startup")
+async def start_database():
+    await database.connect()
+
+
+@app.on_event("shutdown")
+async def close_database():
+    await database.disconnect()
+```
+
+##### add_event_handler
+
+```python hl_lines="3 10-11"
+from saffier import Database, Registry
+
+from starlette_bridge import Starlette
+
+database = Database("sqlite:///db.sqlite")
+models = Registry(database=database)
+
+
+app = Starlette()
+app.add_event_handler("startup", database.connect)
+app.add_event_handler("shutdown", database.disconnect)
+```
+
+## Notes
+
+This is from the same author of [Esmerald](https://esmerald.dev),
+[Starlette Bridge](https://saffier.tarsild.io) and [Asyncz](https://asyncz.tarsild.io). Have a look around
+those techologies as well 😄.
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -1,23 +1,23 @@
 # Contributing
 
-Thank you for showing interes in contributing to Saffier. There are many ways you can help and contribute to the
+Thank you for showing interes in contributing to Starlette Bridge. There are many ways you can help and contribute to the
 project.
 
-* Try Saffier and [report bugs and issues](https://github.com/tarsil/starlette_bridge/issues/new) you find.
-* [Implement new features](https://github.com/tarsil/starlette_bridge/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-* Help othes by [reviewing pull requests](https://github.com/tarsil/starlette_bridge/pulls)
+* Try Starlette Bridge and [report bugs and issues](https://github.com/tarsil/starlette-bridge/issues/new) you find.
+* [Implement new features](https://github.com/tarsil/starlette-bridge/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+* Help othes by [reviewing pull requests](https://github.com/tarsil/starlette-bridge/pulls)
 * Help writting documentation
 * Use the discussions and actively participate on them.
-* Become an contributor by helping Saffier growing and spread the words across small, medium, large or any company
+* Become an contributor by helping Starlette Bridge growing and spread the words across small, medium, large or any company
 size.
 
 ## Reporting possible bugs and issues
 
-It is natural that you might find something that Saffier should support or even experience some sorte of unexpected
+It is natural that you might find something that Starlette Bridge should support or even experience some sorte of unexpected
 behaviour that needs addressing.
 
 The way we love doing things is very simple, contributions should start out with a
-[discussion](https://github.com/tarsil/starlette_bridge/discussions). The potential bugs shall be raised as "Potential Issue"
+[discussion](https://github.com/tarsil/starlette-bridge/discussions). The potential bugs shall be raised as "Potential Issue"
 in the discussions, the feature requests may be raised as "Ideas".
 
 We can then decide if the discussion needs to be escalated into an "Issue" or not.
@@ -37,18 +37,18 @@ it clear to understand and get the required help.
 
 ## Development
 
-To develop for Saffier, create a fork of the [Saffier repository](https://github.com/tarsil/starlette_bridge) on GitHub.
+To develop for Starlette Bridge, create a fork of the [Starlette Bridge repository](https://github.com/tarsil/starlette-bridge) on GitHub.
 
 After, clone your fork with the follow command replacing `YOUR-USERNAME` wih your GitHub username:
 
 ```shell
-$ git clone https://github.com/YOUR-USERNAME/starlette_bridge
+$ git clone https://github.com/YOUR-USERNAME/starlette-bridge
 ```
 
 ### Install the project dependencies
 
 ```shell
-$ cd starlette_bridge
+$ cd starlette-bridge
 $ scripts/install
 ```
 
@@ -60,7 +60,7 @@ To run the tests, use:
 $ scripts/test
 ```
 
-Because Saffier uses pytest, any additional arguments will be passed. More info within the
+Because Starlette Bridge uses pytest, any additional arguments will be passed. More info within the
 [pytest documentation](https://docs.pytest.org/en/latest/how-to/usage.html)
 
 For example, to run a single test_script:
@@ -72,20 +72,20 @@ $ scripts/test tests/test_apiviews.py
 To run the linting, use:
 
 ```shell
-$ scripts/lint
+$ scripts/format
 ```
 
 ### Documentation
 
-Improving the documentation is quite easy and it is placed inside the `starlette_bridge/docs` folder.
+Improving the documentation is quite easy and it is placed inside the `starlette-bridge/docs` folder.
 
 To start the docs, run:
 
 ```shell
 $ scripts/docs
 ```
 
-## Building Saffier
+## Building Starlette Bridge
 
 To build a package locally, run:
 
@@ -103,15 +103,15 @@ It will install the requirements and create a local build in your virtual enviro
 
 ## Releasing
 
-*This section is for the maintainers of `Saffier`*.
+*This section is for the maintainers of `Starlette Bridge`*.
 
-### Building the Saffier for release
+### Building the Starlette Bridge for release
 
 Before releasing a new package into production some considerations need to be taken into account.
 
 * **Changelog**
     * Like many projects, we follow the format from [keepchangelog](https://keepachangelog.com/en/1.0.0/).
-    * [Compare](https://github.com/tarsil/starlette_bridge/compare/) `main` with the release tag and list of the entries
+    * [Compare](https://github.com/tarsil/starlette-bridge/compare/) `main` with the release tag and list of the entries
 that are of interest to the users of the framework.
         * What **must** go in the changelog? added, changed, removed or deprecated features and the bug fixes.
         * What is **should not go** in the changelog? Documentation changes, tests or anything not specified in the
@@ -124,7 +124,7 @@ point above.
 
 #### Releasing
 
-Once the `release` PR is merged, create a new [release](https://github.com/tarsil/starlette_bridge/releases/new)
+Once the `release` PR is merged, create a new [release](https://github.com/tarsil/starlette-bridge/releases/new)
 that includes:
 
 Example:

diff --git a/docs/index.md b/docs/index.md
@@ -1,32 +1,32 @@
-# Saffier
+# Starlette Bridge
 
 <p align="center">
-  <a href="https://starlette-bridge.tarsild.io"><img src="https://res.cloudinary.com/dymmond/image/upload/v1675104815/Saffier/logo/logo_dowatx.png" alt='Saffier'></a>
+  <a href="https://starlette-bridge.tarsild.io"><img width="420px" src="https://www.starlette.io/img/starlette.png" alt='Starlette Bridge'></a>
 </p>
 
 <p align="center">
-    <em>🚀 The only Async ORM you need. 🚀</em>
+    <em>🚀 The Starlette events bridge that you need. 🚀</em>
 </p>
 
 <p align="center">
-<a href="https://github.com/tarsil/starlette_bridge/workflows/Test%20Suite/badge.svg?event=push&branch=main" target="_blank">
-    <img src="https://github.com/tarsil/starlette_bridge/workflows/Test%20Suite/badge.svg?event=push&branch=main" alt="Test Suite">
+<a href="https://github.com/tarsil/starlette-bridge/workflows/Test%20Suite/badge.svg?event=push&branch=main" target="_blank">
+    <img src="https://github.com/tarsil/starlette-bridge/workflows/Test%20Suite/badge.svg?event=push&branch=main" alt="Test Suite">
 </a>
 
-<a href="https://pypi.org/project/starlette_bridge" target="_blank">
-    <img src="https://img.shields.io/pypi/v/starlette_bridge?color=%2334D058&label=pypi%20package" alt="Package version">
+<a href="https://pypi.org/project/starlette-bridge" target="_blank">
+    <img src="https://img.shields.io/pypi/v/starlette-bridge?color=%2334D058&label=pypi%20package" alt="Package version">
 </a>
 
-<a href="https://pypi.org/project/starlette_bridge" target="_blank">
-    <img src="https://img.shields.io/pypi/pyversions/starlette_bridge.svg?color=%2334D058" alt="Supported Python versions">
+<a href="https://pypi.org/project/starlette-bridge" target="_blank">
+    <img src="https://img.shields.io/pypi/pyversions/starlette-bridge.svg?color=%2334D058" alt="Supported Python versions">
 </a>
 </p>
 
 ---
 
 **Documentation**: [https://starlette-bridge.tarsild.io](https://starlette-bridge.tarsild.io) 📚
 
-**Source Code**: [https://github.com/tarsil/starlette_bridge](https://github.com/tarsil/starlette_bridge)
+**Source Code**: [https://github.com/tarsil/starlette-bridge](https://github.com/tarsil/starlette-bridge)
 
 ---
 
@@ -54,3 +54,68 @@ To install Starlette Bridge, simply run:
 ```shell
 $ pip install starlette-bridge
 ```
+
+## How to use
+
+This is actually very simple to do it. You don't need to do anything particularly difficult, in
+fact, you only need to update where your Starlette object comes from.
+
+```python hl_lines="1"
+{! ../docs_src/quickstart.py !}
+```
+
+And that is pretty much it.
+
+### How does it work
+
+Starlette bridge simply maps your `on_startup` and `on_shutdown` events and converts them into
+the new `lifespan` async generator from `Starlette`.
+
+This way you can continue to use your preferred way of assembling the events while maintaining
+the new structure required by Starlette for managing events.
+
+### on_event and add_event_handler
+
+These two pieces of functionality are also supported by the bridge making sure that what you had
+in the past, still remains working as is without changing the syntax.
+
+Let us see an example how it works. We will be using [Starlette Bridge](https://saffier.tarsild.io) because
+already contains events we want to use.
+
+#### on_startup/on_shutdown
+
+Using the `on_startup` and `on_shutdown`.
+
+```python hl_lines="3 10-11"
+{! ../docs_src/events.py !}
+```
+
+#### Lifespan
+
+You can, of course, use the lifespan as well.
+
+```python hl_lines="5 20"
+{! ../docs_src/lifespan.py !}
+```
+
+#### on_event and add_event_handler
+
+As mentioned before, those two functionalities are also available.
+
+##### on_event
+
+```python hl_lines="3 12 17"
+{! ../docs_src/on_event.py !}
+```
+
+##### add_event_handler
+
+```python hl_lines="3 10-11"
+{! ../docs_src/add_event_handler.py !}
+```
+
+## Notes
+
+This is from the same author of [Esmerald](https://esmerald.dev),
+[Starlette Bridge](https://saffier.tarsild.io) and [Asyncz](https://asyncz.tarsild.io). Have a look around
+those techologies as well 😄.
diff --git a/docs/release-notes.md b/docs/release-notes.md
@@ -2,8 +2,8 @@
 
 ## 0.1.0
 
-
 This is the initial release of Starlette Bridge.
 
-* Simmple bridge allowing to keep individual `on_startup`/`on_shutdown` events even those
+* Simple bridge allowing to keep individual `on_startup`/`on_shutdown` events even those
 where depracated by `Starlette`. 
+* `on_event` and `add_event_handler` available to be used like Starlette.