From dab01abf2bb2919472c63017bb795fffaefd54f9 Mon Sep 17 00:00:00 2001
From: DarkCat09 <a.chechkenev@yandex.ru>
Date: Wed, 1 Mar 2023 19:39:12 +0400
Subject: [PATCH] Readme: mariadb note, wtforms and database sections, app
 publishing; Makefile: docker-push

---
 Makefile  |  4 ++++
 README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 53 insertions(+), 4 deletions(-)

diff --git a/Makefile b/Makefile
index d2aa644..f5656d4 100644
--- a/Makefile
+++ b/Makefile
@@ -16,6 +16,10 @@ docker:
 	python3 -m dotenv -f version_code run \
 	docker build -t ${REPO_OWNER_LOWER}/${REPO_NAME_SNAKE}:$$VERSION .
 
+docker-push:
+	python3 -m dotenv -f version_code run \
+	docker push ${REPO_OWNER_LOWER}/${REPO_NAME_SNAKE}:$$VERSION
+
 clean:
 	rm -rf app/__pycache__
 	rm -rf app/*/__pycache__
diff --git a/README.md b/README.md
index a463a5b..b05f85b 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,9 @@ Includes Jinja, WTForms, MySQL ORM and Docker.
 2. For debugging, change the database connection parameters
 in `.env_debug` file correspoding to the configuration
 of MariaDB/MySQL server on your PC
+   1. If you have no MariaDB/MySQL test server installed,
+   search for "[mariadb install (your linux distro)](https://searx.dc09.ru/search?q=mariadb+install+ubuntu)",
+   for example: [an article on DigitalOcean for Ubuntu 22.04](https://url.dc09.ru/mdbu22do)
 3. Edit app [paths](#paths),
 [custom error pages](#custom-error-pages)
 and [forms](#wtforms)
@@ -118,10 +121,46 @@ but you can add your own:
 3. Add (or remove) elements to the list below
 
 ### WTForms
-TODO
+[Related docs page](https://github.com/muicss/starlette-wtf/blob/master/README.md)
+
+Each file in the `app/forms` directory
+contains a WTForms class (or multiple classes).  
+You can simply copy `users.py` content
+to create a form and use it in your project.
+
+Also, there is one helper function in `__init__.py`
+named `get_form` for instantiating WTForms class.  
+It should be preferred to the direct constructor call.
+
+### Sample website
+Included templates and CSS/JS files, paths, forms and SQL database
+are related to the sample website (for showing how the template works)
+and can be deleted or edited, except:
+ - `__init__.py`s
+ - `main.py`
+ - `common.py`
+ - `respond.py`
+ - `paths/errors.py`
 
 ### Database
-TODO
+[Related docs page](https://fastapi.tiangolo.com/tutorial/sql-databases/)
+
+ - SQLAlchemy models are stored in `app/sql/models.py`
+ - Pydantic models (schemas)
+ used for more handy SQLAlchemy models processing
+ are stored in `app/sql/schemas.py`
+ - Functions executing SQL CRUD requests
+ are stored in `app/sql/crud.py`
+
+> **Note**
+> As the official FastAPI documentation recommends (the link is above),
+there are two schemas — `User` and `UserCreate` — for one `User` SQLAlchemy model.
+> The first one is needed for SELECT requests,
+and the second one is for INSERT requests (creating users).
+> The first one contains all information about user,
+but the second one (`UserCreate`) ommits `id` field,
+because we don't want to specify an ID when creating a new user,
+it will be generated automatically by the MariaDB server.
 
 
 ## Helper functions
@@ -235,6 +274,12 @@ Code is copied from the official docs.
 
 
 ## Publishing app
-First of all, build an image: `make docker`  
+First of all, check the `version_code` file and correct it if needed,  
+Then build a Docker image using `make docker` command.
+
 Follow [this documentation page](https://docs.docker.com/get-started/04_sharing_app/)
-to upload your image to Docker Hub.
+to create an account in the Docker Hub.
+
+To publish the image, you can use `make docker-push` command,  
+or manually enter the image name and its tag (version):
+`docker push yourname/yourapp:tag`