docs: Update the documentation to reflect the new changes

engineervix · Jul 21, 2021 · 88941f0 · 88941f0
1 parent 51ad4f9
commit 88941f0
Showing 1 changed file with 95 additions and 45 deletions.
diff --git a/README.md b/README.md
@@ -8,19 +8,32 @@
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
 [![License: MIT](https://img.shields.io/github/license/engineervix/cookiecutter-wagtail-vix)](https://github.com/engineervix/cookiecutter-wagtail-vix/LICENSE)
 
-- [cookiecutter-wagtail-vix](#cookiecutter-wagtail-vix)
-  - [What is this ❓](#what-is-this-)
-  - [:tada: Features](#tada-features)
-  - [:wrench: Prerequisites](#wrench-prerequisites)
-    - [:anchor: Core](#anchor-core)
-    - [🕶 Optional](#-optional)
-  - [:computer: Setup](#computer-setup)
-    - [⌨️ to get started](#️-to-get-started)
-    - [⚙️ other steps](#️-other-steps)
-      - [git workflow](#git-workflow)
-  - [:+1: Credits](#1-credits)
-  - [✍️ To do](#️-to-do)
-  - [📋 Reference](#-reference)
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [What is this ❓](#what-is-this-)
+- [:tada: Features](#tada-features)
+- [:wrench: Prerequisites](#wrench-prerequisites)
+  - [:anchor: Core](#anchor-core)
+  - [🕶 Continuous Integration](#%F0%9F%95%B6-continuous-integration)
+- [:computer: Setup](#computer-setup)
+  - [⌨️ to get started](#-to-get-started)
+  - [⚙️ other steps](#-other-steps)
+    - [git workflow](#git-workflow)
+    - [Python Code Formatting](#python-code-formatting)
+- [:+1: Credits](#1-credits)
+- [✍️ To do](#%EF%B8%8F-to-do)
+  - [Automation](#automation)
+  - [Testing and Code Quality](#testing-and-code-quality)
+  - [CI/CD / Production](#cicd--production)
+  - [Project Features](#project-features)
+  - [Misc](#misc)
+  - [Done](#done)
+  - [Deprecated](#deprecated)
+- [📋 Reference](#-reference)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 ## What is this ❓
 
@@ -32,27 +45,33 @@ Notwithstanding the foregoing, it is nowhere near perfect, and thus remains a wo
 
 ## :tada: Features
 
-- A starting point for a CMS-based website project, with
+- A starting point for a CMS-based website project, with so many batteries included:
   - a homepage and "About" section, which includes addition of key personnel (with position, bio, social profiles, etc.)
   - a minimal functional blog with simplified categories and tags,
-  - a contact page with contact form and location map. Includes SMS support powered by [Nexmo](https://developer.nexmo.com/messaging/sms/overview)
-- Tests written using [pytest](https://docs.pytest.org/en/latest/) in conjunction with [pytest-django](https://pytest-django.readthedocs.io/en/latest/) (plus other pytest plugins), [factory_boy](https://factoryboy.readthedocs.io/en/latest/) and [wagtail-factories](https://github.com/mvantellingen/wagtail-factories). Test coverage currently stands at 92%.
+  - a contact page with contact form and location map. Includes SMS support powered by [Vonage](https://www.vonage.com/) (formerly _Nexmo_)
+- Tests written using [pytest](https://docs.pytest.org/en/latest/) in conjunction with [pytest-django](https://pytest-django.readthedocs.io/en/latest/) (plus other pytest plugins), [factory_boy](https://factoryboy.readthedocs.io/en/latest/) and [wagtail-factories](https://github.com/mvantellingen/wagtail-factories). Test coverage currently stands at about 85%.
 - Latest [Bootstrap 4](https://getbootstrap.com/) with additional themes courtesy of [Bootswatch](https://bootswatch.com/).
 - [Font Awesome 5 (free)](https://fontawesome.com/icons?m=free) icons.
 - [shufflejs](https://vestride.github.io/Shuffle/) — Categorize, sort, and filter a responsive grid of items
 - Live reload courtesy of [BrowserSync](https://browsersync.io/).
-- [Grunt](https://gruntjs.com/) based workflow, with defined tasks for:
+- [Gulp](https://gulpjs.com/) based workflow, with defined tasks for:
   - copying minified (dist) files of modules listed in package.json "dependencies" field to the `static/vendors` directory,
   - deleting files and directories in the `static/vendors` directory,
-  - _uglifying_ javascript files,
+  - transpiling ES6 code to ES5 using [babel](https://babeljs.io/), and _uglifying_ the resulting JS files,
   - _minifying_ css files
   - _watching_ for file changes (in conjunction with BrowserSync)
-- [django-environ](https://github.com/joke2k/django-environ) — allows you to utilize 12factor inspired environment variables to configure your Django application.
-- [django-extensions](https://github.com/django-extensions/django-extensions) — global custom management extensions for the Django Framework. I especially like [`runserver_plus`](https://django-extensions.readthedocs.io/en/latest/runserver_plus.html) (the standard runserver stuff but with the Werkzeug debugger baked in) and [`shell_plus`](https://django-extensions.readthedocs.io/en/latest/shell_plus.html) (Django shell with autoloading of the apps database models and subclasses of user-defined classes).
+- [django-environ](https://github.com/joke2k/django-environ) — allows you to utilize 12factor inspired environment variables to configure your Django application.
+- [django-extensions](https://github.com/django-extensions/django-extensions) — global custom management extensions for the Django Framework. I especially like [`runserver_plus`](https://django-extensions.readthedocs.io/en/latest/runserver_plus.html) (the standard runserver stuff but with the Werkzeug debugger baked in) and [`shell_plus`](https://django-extensions.readthedocs.io/en/latest/shell_plus.html) (Django shell with autoloading of the apps database models and subclasses of user-defined classes).
 - [django-recaptcha](https://github.com/praekelt/django-recaptcha)
 - [django-debug-toolbar](https://github.com/jazzband/django-debug-toolbar) for use during development
-- [django-maintenancemode-2](https://github.com/alsoicode/django-maintenancemode-2) — makes it easy to put your Django site into "maintenance mode", or more technically, return an HTTP 503 response. This project differs slightly from other implementations in that the maintenance mode flag is stored in your database versus settings or an environment variable. If your site is deployed to multiple servers, the centralized database-based maintenance flag makes it a snap to bring them all up or down at once.
-- ... There's definitely much more ...
+- [django-maintenancemode-2](https://github.com/alsoicode/django-maintenancemode-2) — makes it easy to put your Django site into "maintenance mode", or more technically, return an HTTP 503 response. This project differs slightly from other implementations in that the maintenance mode flag is stored in your database versus settings or an environment variable. If your site is deployed to multiple servers, the centralized database-based maintenance flag makes it a snap to bring them all up or down at once.
+- Automatic dependency management via [Renovate](https://github.com/marketplace/renovate)
+- Task execution and automation using [`invoke`](http://www.pyinvoke.org/).
+- Linting using [Black](https://black.readthedocs.io/), [Flake8](https://flake8.pycqa.org/) and [isort](https://pycqa.github.io/isort/)
+- [Celery](https://docs.celeryproject.org/en/stable/) ready
+- Documentation on setting up the project (This README and the generated project's README!)
+- A ready to use VSCode configuration, just update the path to your python executable in the generated `.vscode/settings.json`.
+- ... and so much more ...
 
 ## :wrench: Prerequisites
 
@@ -62,39 +81,43 @@ Notwithstanding the foregoing, it is nowhere near perfect, and thus remains a wo
 - [Node.js](https://nodejs.org/) with the following packages installed **globally**:
   - [concurrently](https://github.com/kimmobrunfeldt/concurrently): `npm install -g concurrently`
   - [Browsersync](https://browsersync.io/): `npm install -g browser-sync`
-  - [Grunt](https://gruntjs.com/): `npm install -g grunt-cli` (Although I've started migrating to [Gulp](https://gulpjs.com/) ... :smile:)
+  - [Gulp](https://gulpjs.com/): `npm install -g gulp-cli`
   - [commitizen](https://github.com/commitizen/cz-cli/): `npm install commitizen -g`
   - [prettier](https://github.com/prettier/prettier/): `npm install prettier -g`
   - [Sass](https://sass-lang.com): `npm install -g sass`
   - [MailDev](https://github.com/maildev/maildev): `npm install -g maildev`
   - [DocToc](https://github.com/thlorenz/doctoc): `npm install -g doctoc`
-  - (optional, but recommended to have it installed on your machine) [lite-server](https://github.com/johnpapa/lite-server): `npm install -g lite-server`
 - [yarn](https://yarnpkg.com/): See [installation instructions](https://classic.yarnpkg.com/en/docs/install#debian-stable)
-- [Python3](https://www.python.org/) (3.6 and above) with [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/), [pyenv](https://github.com/pyenv/pyenv) and ~~[pipev](https://github.com/pypa/pipenv)~~ [pip-tools](https://github.com/jazzband/pip-tools).
-- ~~The wagtail search interface relies on [elasticsearch](https://www.elastic.co/downloads/elasticsearch). If you prefer not to run an Elasticsearch server in development or production, there are many hosted services available, including [Bonsai](https://bonsai.io/signup), who offer a free account suitable for testing and development~~. Switched to the [PostgreSQL Backend](https://docs.wagtail.io/en/latest/topics/search/backends.html#postgresql-backend). Therefore, please ensure that Postgres (and PostGIS) are setup on your machine.
+- [Python3](https://www.python.org/) (3.6 and above) with [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/), [pyenv](https://github.com/pyenv/pyenv) and [pip-tools](https://github.com/jazzband/pip-tools).
+- The project uses the [PostgreSQL Backend](https://docs.wagtail.io/en/latest/topics/search/backends.html#postgresql-backend) for the wagtail search interface. Therefore, please ensure that Postgres (or PostGIS) are setup on your machine.
 
-### 🕶 Optional
+### 🕶 Continuous Integration
+
+The project comes with three Continuous Integration configurations:
+
+- [GitLab CI](https://docs.gitlab.com/ee/ci/yaml/).
+- [CircleCI](https://circleci.com/),
+- [GitHub Actions]()
+
+Simply choose one of the three and delete the others. If you don't like any of these three, feel free to use other options such as [Travis CI](https://travis-ci.org/), [Jenkins](https://jenkins.io/), etc.
 
-- Continuous Integration is via [GitLab CI](https://docs.gitlab.com/ee/ci/yaml/). You can setup CI using alternative services like [CircleCI](https://circleci.com/), [Travis CI](https://travis-ci.org/), [Jenkins](https://jenkins.io/), etc.
-- [VS Code](https://code.visualstudio.com/)
 
 ## :computer: Setup
 
 ### ⌨️ to get started
 
 1. ensure that you have [cookiecutter](https://github.com/audreyr/cookiecutter) installed on your computer
 2. run `cookiecutter https://github.com/engineervix/cookiecutter-wagtail-vix.git` in your favourite shell. You’ll be prompted for some values, such as **project_name**, , **project_slug**, **email**, **wagtail_username** etc. A new wagtail project will be created in a folder named according to the **project_slug** at your current location.
-3. create a virtual environment for your project. `cd` into the project folder created above and install python dependencies: `pip install -r requirements`.
+3. create a virtual environment for your project. `cd` into the project folder created above and install python dependencies: First, install [pip-tools](https://github.com/jazzband/pip-tools): `pip install pip-tools`, then run `pip-compile requirements.in` followed by `pip install -r requirements.txt`.
 4. Now would be a good time to setup your postgres/postgis database and ensure that you update `DATABASE_URL` and the other environment variables in your `.env` files. The essential ones for starters are `RECAPTCHA_PUBLIC_KEY`, `RECAPTCHA_PRIVATE_KEY` and `MAPBOX_ACCESS_TOKEN`.
 5. `export ENV_PATH=.envs/.dev.env`
 6. `./manage.py migrate`
 7. `./manage.py createsuperuser`. When prompted for a username, please use the **wagtail_username** you specified in step 2. This is important to ensure that you don't have issues when populating the database with initial data, which is tied to the username provided in step 2.
 8. `./manage.py load_initial_data`
 9. `yarn`
-10. `grunt all`
-11. `./manage.py collectstatic`
-12. Prior to running tests, check the `package.json` to ensure that you have the correct postgres/postgis settings. Once you're all set, go ahead and run tests: `npm run test`
-13. Start the development server: `npm run dev`. Your site should be accessible at `http://127.0.0.1:3000` or `http://localhost:3000`.
+10. `gulp cp`
+11. Prior to running tests, check the `package.json` to ensure that you have the correct postgres/postgis settings. Once you're all set, go ahead and run tests: `yarn test`.
+12. Start the development server: `yarn dev`. Your site should be accessible at `http://127.0.0.1:3000` or `http://localhost:3000`.
 
 ### ⚙️ other steps
 
@@ -124,6 +147,11 @@ Notwithstanding the foregoing, it is nowhere near perfect, and thus remains a wo
 
 > :exclamation: If you make any changes to the structure of your README.md or other markdown files, do `npm run toc` before committing, so that the TOC is updated
 
+#### Python Code Formatting
+
+- Run `invoke lint` to run [`flake8`](https://flake8.pycqa.org/en/latest/), [`black`](https://black.readthedocs.io/en/stable/), [`isort`](https://pycqa.github.io/isort/) on the code.
+- If you get any errors from `black` and/or `isort`, run `invoke lint --fix` or `invoke lint -f` so that black and isort can format your files. If this still doesn't work, don't worry, there's a bunch of pre-commit hooks that that have been set up to deal with this. Take a look at [.pre-commit-config.yaml](.pre-commit-config.yaml).
+
 ## :+1: Credits
 
 - `.gitignore` generated using <https://www.gitignore.io/>
@@ -137,23 +165,45 @@ Notwithstanding the foregoing, it is nowhere near perfect, and thus remains a wo
 
 ## ✍️ To do
 
-- [ ] Make the `Makefile` functional
-- [ ] Automate Steps 1 to 10 by adding these in the `post_gen_project` hook or incorporating them in the `Makefile`
+### Automation
+
+- [ ] Automate Steps 1 to 10 by adding these in the `post_gen_project` hook or incorporating them in invoke's `tasks.py`
 - [ ] The cookiecutter prompt asks if you wanna use bootswatch themes. If you say "n", it shouldn't prompt you with another question on which bootswatch theme to use! See [this](https://github.com/polyswarm/participant-template/issues/2) and [that](https://github.com/cookiecutter/cookiecutter/issues/913).
-- [X] Write tests and setup CI for this cookiecutter package
+
+
+### Testing and Code Quality
+
 - [ ] Improve test coverage for the generated wagtail project
-- [ ] Setup browser-based testing and production-level testing
-- [ ] Improve the Gitlab CI pipeline for the generated wagtail project
-- [ ] Possibly add support for other popular CI options (CircleCI, Travis)
+- [ ] Setup integrated tests / e2e tests (Cypress / Selenium ?)
+- [ ] Improve on code style (*This is already in progress*)
+
+
+### CI/CD / Production
+
 - [ ] Add docker support
-- [ ] Add support for different Databases right from the beginning.
-- [ ] Add better production-level support (serving static assets, mail, caching, perfomance, task queues, Nginx and uWsgi/Gunicorn configuration, etc.)
-- [ ] Add `Gulp` support
-- [ ] Improve on code style
+- [ ] Improve the CI/CD pipelines for the generated wagtail project, to handle automatic deployments
+- [ ] Add better production-level features to make it easy to move from development to production (serving static assets, mail, caching, perfomance, task queues, Nginx and uWsgi/Gunicorn configuration, etc.) (*This is already in progress*)
+
+### Project Features
+
 - [ ] Generate RSS Feeds from Blog
-- [ ] Gotta add those [badges](https://shields.io/) :wink:
 - [ ] Add custom `sitemap.xml` and `robots.txt`
 
+### Misc
+
+- [ ] Add some more [badges](https://shields.io/) if need be :wink:
+
+### Done
+
+- [X] ~~Make the `Makefile` functional~~ I've removed the `Makefile` and [replaced it with *invoke*](https://importthis.tech/task-execution-and-automation-using-invoke).
+- [X] Write tests and setup CI for this cookiecutter package
+- [X] Possibly add support for other popular CI options (added CircleCI and GitHub Actions)
+- [X] Add `Gulp` support (No longer using `Grunt`)
+
+### Deprecated
+
+- [X] ~~Add support for different Databases right from the beginning~~. Use Postgres/PostGIS.
+
 ## 📋 Reference
 
 The data was dumped as follows: