Full Readme, .env_debug

.env_debug

@@ -0,0 +1,5 @@
+MYSQL_HOST=localhost
+MUSQL_PORT=3306
+MYSQL_USER=darkcat09
+MYSQL_PASSWORD=
+MYSQL_DATABASE=flasktest

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.

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

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]
 
 

flaskapp/exts.py

@@ -4,4 +4,6 @@ from flaskext.mysql import MySQL  # type: ignore
 
 
 sql = MySQL(autocommit=True)
+
+# Add your extensions here
 exts = [sql]