Feature: Reworked documentation

README.md

@@ -4,6 +4,26 @@ A production-ready template for Django applications
 ## Introduction
 This Django template was created out of a need for consistent structure for projects with a setup that's easy to understand and use with as minimal additional setup as possible.
 
+### How to use
+Three commands and you're good to go:
+- `cp .env.example .env`
+- `make build`
+- `make up`
+
+A much detailed explanation is in the [How to use (fleshed-out)](#how-to-use-fleshed-out) section.
+
+## Features
+- Uses standard Django application structure. No folder complexities to be navigated through.
+- Drop-in template, two commands and you have all the features at your fingertips: `make build && make up`
+- Built-in simple Docker set up that just works!
+- Support for .env files and typed environmental variables using Pydantic. Try running your application without needed environment variables and it crashes immediately, fail-fast without future tears.
+- First class support for Postgres. Just add `DATABASE_URL` in your `.env` file.
+- Uses lightning fast Ruff for both formatting and linting. Drop-in replacement for Black and Isort and 10 - 100x faster too!
+- Easy way to run commands using `make`. Run migrations with `make migrate`, start application with `make up`. No need to memorize verses of commands.
+- Included GitHub workflow for running tests
+- Environment based settings file
+- Everything you need to start implementing your first API.
+
 ### What is hoped to be achieved
 - Simplicity; no need for bloated classes and huge utils that you'll likely never use. Everything here should be very much needed in most projects
 - Low barrier for entry; a template that is easy to start with and does not seem too advanced for beginners to use
@@ -14,7 +34,7 @@ This Django template was created out of a need for consistent structure for proj
 - Utility dump; this template will not be where all sorts of utilities are dumped because, 'why not?'.
 - I'm out of points, sorry. This kind of stuff should be like 3 points or so, but then...
 
-## How to use: For mere mortals
+## How to use (Fleshed out)
 ### Requirements:
 - Make, Docker and Docker Compose
 
@@ -46,22 +66,83 @@ Lol, I told you to use Docker.
 - You can start making requests by visiting [http://127.0.0.1:8000](http://127.0.0.1:8000)
 - Edit the template as you want for your app (switch to Docker)
 
+## Glossary
+This section contains a list of commonly needed helps while working on this project.
+
+Majority of the commands you'll need are in the Makefile and can be run as:
+```
+make <command>
+```
+
+### All needed commands currently in the Makefile
+- up: start up the containers
+- bash: starts a bash shell for the application
+- build: builds the containers only
+- build-up: builds and starts the containers
+- createsuperuser: spawns the Django app to create a superuser
+- down: stops the containers
+- format: runs isort and black on the codebase to make it fine
+- flush-db: empties the database and begins the DB from scratch
+- install: installs all dependencies in a virtual env locally
+- lint: runs ruff to sort import and format the code
+- migrations: creates migrations based on DB schema
+- migrate: runs the created migrations
+- resetdb: resets the database, deletes everything including the database itself
+- run-command: runs a command in the Django app context. For example, `make run-command command="python manage.py test"`
+- shell: spawns a shell within the Django app context. The same as `manage.py shell`.
+- test: runs the test suite using pytest
+- testcase: runs a single test case. For example, `make testcase testcase="tests/test_models.py::TestUserModel::test_user_can_be_created"`
+- up-d: starts up the container without logs
+
+### How do I run commands in Docker?
+First check the list above if the command you need is there. If it is, you can run it as `make <command>`. For example, to run tests, I can do: `make test`. If it isn't, continue reading.
+
+Ideally, you should be using `make run-command command="<command>"`. For example, to run tests, I can do: `make run-command command="python manage.py test"`.
+
+However, if you're not using make, you can run commands in Docker using the syntax: `docker compose run <name-of-container-volume> <command>`. For example, to run tests, I can do: `docker compose run web python manage.py test`.
+
+### How do I enable auto-imports for libraries on VSCode
+- Outside of docker, run `make install`
+- Start a virtual environment in the root folder by running `pipenv shell`
+- On your VSCode, at the bottom right corner, you'll see a Python version, click on it and select the Python interpreter created from your virtual environment.
+You can continue your work inside docker.
+
+## Change Log
+### 31-01-2023
+- Initial release
+- Added support for Postgres
+- Added support for .env files
+- Added support for typed environmental variables using Pydantic
+- Added Docker support
+
+### 20-02-2023
+- Added Make command for formatting and linting
+
+### 13-01-2024
+- Added auto removal of containers when running one-off commands
+
+### 24-01-2024
+- Trim down Dockerfile to reduce needless steps and upgrade python version
+- Added extensions for resetting db
+- Added command to run any command on app shell
+- Replaced test runner with pytest
+- Renamed `makemigrations` command to `migrations`
+- Removed black and ruff
+- Upgraded pydantic
+- Replaced linter and formatter with ruff
+- Bumped Python version to 3.12
+- Added environment based settings file
+- Added changelog
+
 
-*Note:*
-The majority of the docs is found in the [Contributions section](CONTRIBUTIONS/README.md).
-Check it if (when) you need help.
 
 ## Got problems?
 Raise an issue.
 
 ## FAQs
 1.
-    Q: Why do you insiste I use Docker?
+    Q: Why do you insist I use Docker?
 
     A: It is actually easier to use and setup
-
-2.
-    Q: Why do you use `master` as the default branch?
-
-    A: To make the codebase look older and more matured than it actually is.
-    Don't lie, you respect `master` more than `main` (what those NodeJS children love).
+    than the alternative. You can also easily
+    switch to the alternative if you want to.