convert README to web docs.

Signed-off-by: Grant Ramsay <seapagan@gmail.com>

Author: seapagan

docs/explanation.md

@@ -0,0 +1,4 @@
+# Code Explanation
+
+!!! note "Under Construction"
+    This section is still to be written.

docs/index.md

@@ -0,0 +1,22 @@
+# Async SQLAlchemy 2 with FastAPI
+
+## Introduction
+
+I've been using [FastAPI][fastapi]{:target="_blank"} and
+[SQLAlchemy][sqla]{:target="_blank"} combined with
+[encode/databases][databases]{:target="_blank"} for a while now.
+
+The `databases` package is a great wrapper around `SQLAlchemy` that allows you
+to use async/await with SQLAlchemy.
+
+However, this does not seem be be actively maintained anymore. So I decided to
+give the new [Async SQLAlchemy][async-sqla]{:target="_blank"} a try instead.
+
+This repository contains a very simple example how to use FastAPI with Async
+SQLAlchemy 2.0, in `ORM` mode. I'll probably add an example for `Core` mode
+also.
+
+[fastapi]:https://fastapi.tiangolo.com/
+[sqla]: https://www.sqlalchemy.org/
+[databases]:https://www.encode.io/databases/
+[async-sqla]:https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html

docs/license.md

@@ -0,0 +1,7 @@
+# License
+
+This project is licensed under the terms of the MIT license.
+
+```pre
+--8<-- "LICENSE.txt"
+```

docs/usage.md

@@ -0,0 +1,85 @@
+# Using this example
+
+## Installation
+
+Clone the repository and install the dependencies. This project uses
+[Poetry][poetry]{:target="_blank"} for dependency management which should be
+installed on your system first.
+
+```console
+poetry install
+```
+
+Then switch to the virtual environment:
+
+```console
+poetry shell
+```
+
+## Usage
+
+Run the server using `Uvicorn`:
+
+```console
+uvicorn main:app --reload
+```
+
+> You can also run the server by just executing the `main.py` file:
+>
+> ```console
+> python main.py
+> ```
+
+Then open your browser at [http://localhost:8000](http://localhost:8000).
+
+There is only one endpoint available: `/users`. It returns a list of all users
+for a `GET` request and creates a new user for a `POST` request.
+
+### Local Postgres server using Docker
+
+This example uses [PostgreSQL][postgres]{:target="_blank"} as the database. If
+you dont have a local PostgreSQL database running, you can start one with
+[Docker][docker]{:target="_blank"} using the following command:
+
+```console
+docker run \
+  --rm   \
+  --name  postgres \
+  -p 5432:5432 \
+  -e POSTGRES_USER=postgres \
+  -e POSTGRES_PASSWORD=postgres \
+  -e POSTGRES_DB=postgres \
+  -d postgres
+```
+
+This will run a PostgreSQL database in a Docker container in the background.
+When you are finished and want to stop the database, run:
+
+```console
+docker stop postgres
+```
+
+If needed, you can connect to the database managment by :
+
+```console
+docker exec -it postgres psql -U postgres
+```
+
+This will allow you to edit or delete the database or records.
+
+### Use SQLite instead of PostgreSQL
+
+For testing purposes, you can also use [SQLite][sqlite]{:target="_blank"}
+instead of PostgreSQL. To do so, open the `db.py` file and comment out the
+PostgreSQL database in the `DATABASE_URL` environment variable and uncomment the
+SQLite database.
+
+```python
+# DATABASE_URL = "postgresql+asyncpg://postgres:postgres@localhost/postgres"
+DATABASE_URL = "sqlite+aiosqlite:///./test.db"
+```
+
+[poetry]: https://python-poetry.org/
+[postgres]:https://www.postgresql.org/
+[docker]:https://www.docker.com/
+[sqlite]:https://www.sqlite.org/

mkdocs.yml

@@ -0,0 +1,42 @@
+site_name: Async SQLAlchemy 2 with FastAPI
+
+repo_url: https://github.com/seapagan/fastapi_async_sqlalchemy2_example
+repo_name: fastapi_async_sqlalchemy2
+
+theme:
+  name: material
+  features:
+    - navigation.footer
+    - navigation.expand
+
+extra:
+  social:
+    - icon: material/web
+      link: https://www.gnramsay.com
+    - icon: fontawesome/brands/github
+      link: https://github.com/seapagan
+    - icon: fontawesome/brands/twitter
+      link: https://twitter.com/gnramsay-dev
+
+plugins:
+  - search
+  - minify:
+      minify_html: true
+      minify_css: true
+      minify_js: true
+      htmlmin_opts:
+        remove_comments: true
+
+markdown_extensions:
+  - admonition
+  - pymdownx.snippets
+  - pymdownx.highlight:
+      linenums: false
+      auto_title: false
+  - attr_list
+
+nav:
+  - Home: index.md
+  - Usage: usage.md
+  - Code Description: explanation.md
+  - License: license.md

models.py

@@ -1,3 +1,4 @@
+"""Define Models used in this example."""
 from sqlalchemy import Column, Integer, String
 
 from db import Base

poetry.lock

@@ -13,6 +13,11 @@ asyncpg = "^0.27.0"
 sqlalchemy = {extras = ["asyncio"], version = "^2.0.16"}
 uvicorn = {extras = ["standard"], version = "^0.22.0"}
 aiosqlite = "^0.19.0"
+mkdocs = "^1.4.3"
+mkdocs-material = "^9.1.16"
+mkdocs-minify-plugin = "^0.6.4"
+pymdown-extensions = "^10.0.1"
+pygments = "^2.15.1"
 
 [tool.poetry.group.dev.dependencies]
 # linting and formatting tools