From dcced28f8473323a6e4d76cef222a184f0af1e54 Mon Sep 17 00:00:00 2001
From: DarkCat09 <a.chechkenev@yandex.ru>
Date: Fri, 17 Feb 2023 17:49:41 +0400
Subject: [PATCH] Full Readme, .env_debug

---
 .env_debug       |  5 ++++
 README.md        | 75 ++++++++++++++++++++++++++++++++++++++++++++++++
 flaskapp/app.py  |  6 ++--
 flaskapp/db.py   |  2 ++
 flaskapp/exts.py |  2 ++
 5 files changed, 88 insertions(+), 2 deletions(-)
 create mode 100644 .env_debug

diff --git a/.env_debug b/.env_debug
new file mode 100644
index 0000000..e13790a
--- /dev/null
+++ b/.env_debug
@@ -0,0 +1,5 @@
+MYSQL_HOST=localhost
+MUSQL_PORT=3306
+MYSQL_USER=darkcat09
+MYSQL_PASSWORD=
+MYSQL_DATABASE=flasktest
diff --git a/README.md b/README.md
index 75c5894..f173b24 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,76 @@
 # Flask App Template
+It is a simple Gitea template for a Flask web application.
+
+
+## Features
+ - Basic Flask app
+ - `@route`s are defined in classes inherited from flaskapp.routes.Routes,
+ so they can be separated into multiple modules
+ - Flask WTForms extension
+ - MySQL/MariaDB database
+ - Gunicorn for production deployment
+ - AutoPEP8 formatter, MyPy and Pylint
+ - Dockerfile, compose YAML config
+
+
+## Usage
+1. Create a repository from this template
+2. For debugging, edit `.env_debug` file corresponding to
+configuration of MySQL/MariaDB installed on your PC
+3. Edit `pages.py`: add your own Flask routes
+4. Edit or delete `admin.py` (its content is similar to `pages.py`)
+5. Create your own Jinja templates in `templates/` directory,
+I recommend to edit `base.html` and inherit other templates from it
+6. Edit or delete `forms.py` (it is used for storing wtforms classes)
+7. Edit routes, error pages and
+(if needed) add other Flask extensions,
+as described in the [next section](#add-routes-exts-error-pages)
+8. Edit `db/schema.sql` corresponding to your database structure
+9. Check `Makefile`, `Dockerfile`, `docker-compose.yml`
+10. Run formatter and linters (`make format`, then `make check`)
+
+
+## Add routes, exts, error pages
+
+### To use your own routes file:
+1. Create a file with the same content as `pages.py`
+2. Give the `RoutePages` class another name
+3. Edit `add_routes` method
+4. Then, open `app.py`
+5. Find the comment `# Add your routes...`
+6. Import the created module (routes file)
+7. Add the routes class from the module
+to the `routes` list
+
+### Custom error pages
+1. Open `errors.py`
+2. Find the comment `# Add other...`
+3. Edit the list below corresponding to
+which HTTP error pages you want to customize
+4. Create templates for these errors,
+e.g. `404.html` for custom 404 page
+
+### Other Flask extensions
+1. Open `exts.py`
+2. Find the comment `# Add your extensions...`
+3. Create extensions objects above, like for Flask-MySQL
+4. Then edit the list below the comment
+corresponding to the added extensions
+
+
+## Makefile
+Make commands:
+|Command|Description|
+|:-----:|:----------|
+|`make format`|Format the code using AutoPEP8|
+|`make check`|Check the code with linters (MyPy, Pylint)|
+|`make dev`|Run the app in development mode|
+|`make prod`|Run production server|
+|`make docker`|Build a docker image from `Dockerfile`|
+|`make clean`|Clean all cache|
+
+
+## Publishing app
+First of all, build an image: `make docker`  
+Follow [this documentation page](https://docs.docker.com/get-started/04_sharing_app/)
+to upload your image to Docker Hub.
diff --git a/flaskapp/app.py b/flaskapp/app.py
index 45a9db3..5ec1bc0 100644
--- a/flaskapp/app.py
+++ b/flaskapp/app.py
@@ -11,11 +11,13 @@ from dotenv import load_dotenv
 from flask import Flask
 
 from . import exts
+from . import db
+
+# Add your routes here
 from .routes import Routes
 from . import pages
 from . import admin
 from . import errors
-from . import db
 
 routes: List[Type[Routes]] = [
     pages.RoutePages,
@@ -37,7 +39,7 @@ def create_app() -> Flask:
     # Load sample configuation
     if app.debug:
         load_dotenv(
-            Path(__file__).parent.parent / '.env'
+            Path(__file__).parent.parent / '.env_debug'
         )
     # Get the token from environment
     # or generate it using secrets
diff --git a/flaskapp/db.py b/flaskapp/db.py
index 1a28c83..504454a 100644
--- a/flaskapp/db.py
+++ b/flaskapp/db.py
@@ -9,7 +9,9 @@ from pymysql.cursors import Cursor
 
 from . import exts
 
+# SQL table name (used for the sample page)
 TABLE = '${REPO_NAME_SNAKE}'
+
 db_obj: List[Optional[Connection]] = [None]
 
 
diff --git a/flaskapp/exts.py b/flaskapp/exts.py
index 2b10bb4..27223c8 100644
--- a/flaskapp/exts.py
+++ b/flaskapp/exts.py
@@ -4,4 +4,6 @@ from flaskext.mysql import MySQL  # type: ignore
 
 
 sql = MySQL(autocommit=True)
+
+# Add your extensions here
 exts = [sql]