Merge pull request #30 from Promptly-Technologies-LLC/16-extend-documentation

16 extend documentation

Author: chriscarrollsmith

.gitignore

@@ -1,4 +1,8 @@
 .devcontainer
 __pycache__
 *.pyc
-.env
+.env
+/.quarto/
+_docs/
+.pytest_cache/
+.mypy_cache/

.nojekyll

@@ -1,60 +1,55 @@
-# README
+# FastAPI, Jinja2, PostgreSQL Webapp Template
 
+![Screenshot of homepage](docs/static/Screenshot.png)
 
-## FastAPI, Jinja2, PostgreSQL Webapp
+## Documentation
 
-![Screenshot of homepage](static/Screenshot.png)
+This README provides a high-level overview. See the **[full documentation website](https://promptlytechnologies.com/fastapi-jinja2-postgres-webapp/docs/)** for more detailed information on installation, features, architecture, conventions and code style, customization, and deployment to cloud platforms.
 
-This project is still under development.
+## Features
 
-### Architecture
+*FastAPI, Jinja2, PostgreSQL Webapp Template* combines three of the most lightweight and performant open-source web development frameworks in existence into a customizable webapp template with:
 
-This application uses a Post-Redirect-Get (PRG) pattern. The user
-submits a form, which sends a POST request to a FastAPI endpoint on the
-server. The database is updated, and the user is redirected to a GET
-endpoint, which fetches the updated data and re-renders the Jinja2 page
-template with the new data.
+- Pure Python backend
+- Low-Javascript frontend
+- Powerful, easy-to-manage database layer
 
-![Webapp Flow](static/webapp_flow.png)
+The template also includes full-featured secure auth with:
 
-The advantage of the PRG pattern is that it is very straightforward to
-implement and keeps most of the rendering logic on the server side. The
-disadvantage is that it requires an extra round trip to the database to
-fetch the updated data, and re-rendering the entire page template may be
-less efficient than a partial page update on the client side.
+- Token-based authentication
+- Password recovery flow
+- Role-based access control system
 
-### Install development dependencies in a VSCode Dev Container
+The design philosophy of the template is to prefer low-level, best-in-class open-source frameworks that offer flexibility, scalability, and performance without vendor-lock-in. You'll find the template amazingly easy not only to understand and customize, but also to deploy to any major cloud hosting platform.
 
-If you use VSCode with Docker to develop in a container, the following
-VSCode Dev Container configuration will install all dependencies:
+## Tech stack
 
-``` json
-{
-    "name": "Python 3",
-    "image": "mcr.microsoft.com/devcontainers/python:1-3.12-bullseye",
-    "postCreateCommand": "sudo apt update && sudo apt install -y python3-dev libpq-dev graphviz && pipx install poetry && poetry install && poetry shell",
-    "features": {
-        "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {},
-        "ghcr.io/rocker-org/devcontainer-features/quarto-cli:1": {}
-    }
-}
-```
+**Core frameworks:**
+- [FastAPI](https://fastapi.tiangolo.com/): scalable, high-performance, type-annotated Python web backend framework
+- [PostgreSQL](https://www.postgresql.org/): the world's most advanced open-source database engine
+- [Jinja2](https://jinja.palletsprojects.com/en/3.1.x/): frontend HTML templating engine
+- [SQLModel](https://sqlmodel.tiangolo.com/): easy-to-use Python ORM
+
+**Additional technologies:**
+- [Poetry](https://python-poetry.org/): Python dependency manager
+- [Pytest](https://docs.pytest.org/en/7.4.x/): testing framework
+- [Docker](https://www.docker.com/): development containerization
+- [Github Actions](https://docs.github.com/en/actions): CI/CD pipeline
+- [Quarto](https://quarto.org/docs/): simple documentation website renderer
+- [MyPy](https://mypy.readthedocs.io/en/stable/): static type checker for Python
+- [Bootstrap](https://getbootstrap.com/): HTML/CSS styler
+- [Resend](https://resend.com/): zero- or low-cost email service used for password recovery
 
-Simply create a `.devcontainer` folder in the root of the project and
-add a `devcontainer.json` file in the folder with the above content.
-VSCode may prompt you to install the Dev Container extension if you
-haven’t already, and/or to open the project in a container. If not, you
-can manually select “Dev Containers: Reopen in Container” from View \>
-Command Palette.
+## Quickstart
 
-### Install development dependencies manually
+For comprehensive installation instructions, see the [documentation website](https://promptlytechnologies.com/fastapi-jinja2-postgres-webapp/docs/).
 
-#### Python and Docker
+### Python and Docker
 
 - [Python 3.12 or higher](https://www.python.org/downloads/)
 - [Docker and Docker Compose](https://docs.docker.com/get-docker/)
 
-#### PostgreSQL headers
+### PostgreSQL headers
 
 For Ubuntu/Debian:
 
@@ -72,28 +67,7 @@ For Windows:
 
 - No installation required
 
-#### Quarto CLI and Graphviz
-
-- [Quarto CLI](https://quarto.org/docs/get-started/)
-
-For macOS:
-
-``` bash
-brew install graphviz
-```
-
-For Ubuntu/Debian:
-
-``` bash
-sudo apt update && sudo apt install -y graphviz
-```
-
-For Windows:
-
-- Download and install from
-  [Graphviz.org](https://graphviz.org/download/#windows)
-
-#### Python dependencies
+### Python dependencies
 
 1.  Install Poetry
 
@@ -113,22 +87,17 @@ poetry install
 poetry shell
 ```
 
-(Note: You will need to activate the shell every time you open a new
-terminal session. Alternatively, you can use the `poetry run` prefix
-before other commands to run them without activating the shell.)
+(Note: You will need to activate the shell every time you open a new terminal session. Alternatively, you can use the `poetry run` prefix before other commands to run them without activating the shell.)
 
 ### Set environment variables
 
 Copy .env.example to .env with `cp .env.example .env`.
 
-Generate a 256 bit secret key with `openssl rand -base64 32` and paste
-it into the .env file.
+Generate a 256 bit secret key with `openssl rand -base64 32` and paste it into the .env file.
 
 Set your desired database name, username, and password in the .env file.
 
-To use password recovery, register a [Resend](https://resend.com/)
-account, verify a domain, get an API key, and paste the API key into the
-.env file.
+To use password recovery, register a [Resend](https://resend.com/) account, verify a domain, get an API key, and paste the API key into the .env file.
 
 ### Start development database
 
@@ -138,8 +107,7 @@ docker compose up -d
 
 ### Run the development server
 
-Make sure the development database is running and tables and default
-permissions/roles are created first.
+Make sure the development database is running and tables and default permissions/roles are created first.
 
 ``` bash
 uvicorn main:app --host 0.0.0.0 --port 8000 --reload
@@ -153,22 +121,10 @@ Navigate to http://localhost:8000/
 mypy .
 ```
 
-### Render the README
-
-When updating the documentation, remember to make changes in the
-README.qmd file, not the README.md file. Then run the following command
-to render the README.md file:
-
-``` bash
-quarto render README.qmd
-```
-
 ### Contributing
 
-Fork the repository, create a new branch, make your changes, and submit
-a pull request.
+Your contributions are welcome! See the [issues page](https://github.com/promptly-technologies-llc/fastapi-jinja2-postgres-webapp/issues) for ideas. Fork the repository, create a new branch, make your changes, and submit a pull request.
 
 ### License
 
-This project is licensed under the MIT License. See the LICENSE file for
-more details.
+This project is licensed under the MIT License. See the LICENSE file for more details.