Giters

kemetmed / kemet-wag-vix

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Welcome to cookiecutter-wagtail-vix 👋

CircleCI Coverage Status python3 Requirements Status Code style: black pre-commit License: MIT GitHub commits since latest release (by SemVer) Conventional Commits Commitizen friendly

a batteries-included, reusable Wagtail project skeleton to serve as a starting point for a CMS-based website project.

demo.gif

Contents generated with DocToc

Features ✨

  • An opinionated 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 Vonage (formerly Nexmo)
  • Tests written using pytest in conjunction with pytest-django (plus other pytest plugins), factory_boy and wagtail-factories. Test coverage currently stands at about 85%.
  • Custom Bootstrap 4 Compilation using Sass.
  • Font Awesome 5 (free) icons.
  • shufflejs — Categorize, sort, and filter a responsive grid of items
  • Live reload courtesy of BrowserSync.
  • Gulp 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,
    • transpiling ES6 code to ES5 using babel, and uglifying the resulting JS files,
    • compiling SCSS to CSS and minifying css files
    • watching for file changes (in conjunction with BrowserSync)
  • django-environ — allows you to utilize 12factor inspired environment variables to configure your Django application.
  • django-extensions — global custom management extensions for the Django Framework. I especially like runserver_plus (the standard runserver stuff but with the Werkzeug debugger baked in) and shell_plus (Django shell with autoloading of the apps database models and subclasses of user-defined classes).
  • django-recaptcha
  • django-debug-toolbar for use during development
  • 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
  • Task execution and automation using invoke.
  • Linting using Black, Flake8 and isort
  • Celery 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.
  • The project comes with three Continuous Integration configurations (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, Jenkins, etc.):

Dev Setup 💻

First things first

  • A *nix environment is highly recommended. Although you can possibly develop on Windows too (if you do, and you're using Powershell or CMD, you'll probably have to adapt some commands to suit a Windows Environment, because these docs assume you're running in a *nix environment)
  • Node.js with the following packages installed globally:
  • yarn: See installation instructions
  • Python3 (3.6 and above) with virtualenvwrapper, pyenv and pip-tools.
  • The project uses the PostgreSQL Backend for the wagtail search interface. Therefore, please ensure that Postgres (or PostGIS) are setup on your machine.

Getting Started

  1. ensure that you have 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_user_email 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 and and pip install --upgrade pip. Thereafter, cd into the project folder created above and install python dependencies: First, install pip-tools: pip install pip-tools, then run pip-compile requirements.in followed by pip-sync.
  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 makemigrations followed by ./manage.py migrate
  7. ./manage.py createsuperuser. When prompted for an email address, please use the wagtail_user_email 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 email address provided in step 2.
  8. ./manage.py load_initial_data
  9. yarn
  10. gulp cp
  11. Prior to running tests, check 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

  • setup version control (git) for your generated project
  • setup pre-commit:
    1. pre-commit install
    2. pre-commit install --hook-type commit-msg
    3. pre-commit run --all-files

❗ If you are using pyenv, see pre-commit/pre-commit#810. In particular, I found this explanation from @thomasfowler and this comment from @asottile to be very helpful.

git Workflow

  1. ⚠️ First, ensure that, before you make any changes, you have pulled the latest changes from remote.
  2. Add the file(s) you wanna commit: git add whatever
  3. git commit -- this will run Commitizen; you'll be prompted to fill in any required fields and your commit messages will be formatted according to cz-conventional-changelog – a Commitizen adapter which prompts for conventional changelog standard.
  4. If there are no issues, push your changes accordingly, otherwise, repeat steps 1 and 2 above until all issues are resolved.

❗ If you encounter stylelint errors, you might wanna run yarn css-fix to try and fix such errors. This is likely to happen on first commit!

❗ If you make any changes to the structure of your README.md or other markdown files, do yarn toc before committing, so that the TOC is updated

Python Code Formatting

  • Run invoke lint to run flake8, black, 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.

TODO ✅

Automation

  • Automate Steps 1 to 10 by adding these in the post_gen_project hook or incorporating them in invoke's tasks.py

Testing and Code Quality

  • Improve test coverage for the generated wagtail project
  • Setup integrated tests / e2e tests (Cypress / Selenium ?)
  • Improve on code style (This is already in progress)

CI/CD / Production

  • Add docker support
  • Improve the CI/CD pipelines for the generated wagtail project, to handle automatic deployments

Project Features

  • Generate RSS Feeds from Blog
  • Add custom sitemap.xml and robots.txt

Done

  • Make the Makefile functional I've removed the Makefile and replaced it with invoke.
  • Write tests and setup CI for this cookiecutter package
  • Possibly add support for other popular CI options (added CircleCI and GitHub Actions)
  • Add Gulp support (No longer using Grunt)
  • Add some more badges if need be 😉
  • Add better production-level features to make it easy to move from development to production (serving static assets, mail, caching, performance, task queues, Nginx and uWsgi/Gunicorn configuration, etc.) (This is always a work in progress, will continue updating as necessary)

Deprecated

  • Add support for different Databases right from the beginning. Even though this cookiecuter generates an SQLite DATABASE_URL for you, some of the generated project's features (like search) depend on using Postgres, so you should use Postgres/PostGIS.
  • 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 and that. Since we're customizing bootstrap using Sass, no need to use bootswatch.

Contributing 🤝

Contributions, issues and feature requests are most welcome! A good place to start is by helping out with the unchecked items in the TODO section above!

Feel free to check the issues page and take a look at the contributing guide before you get started. In addition, please note the following:

  • if you're making code contributions, please try and write some tests to accompany your code, and ensure that the tests pass. Also, where necessary, update the docs so that they reflect your changes.
  • commit your changes via cz commit. Follow the prompts. When you're done, pre-commit will be invoked to ensure that your contributions and commits follow defined conventions. See pre-commit-config.yaml for more details.
  • your commit messages should follow the conventions described here. Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert. Once you are done, please create a pull request.

Show your support

Please give a ⭐️ if this project helped you!

Credits 👏

Reference 📋

The data was dumped as follows:

./manage.py dumpdata --natural-foreign --indent 2 \
    -e contenttypes -e auth \
    -e wagtailcore.groupcollectionpermission \
    -e wagtailcore.grouppagepermission -e wagtailimages.rendition \
    -e postgres_search.indexentry -e users.user \
    -e sessions > data.json

Author

👤 Victor Miti

License 📝

Copyright © 2021 Victor Miti.

This project is licensed under the terms of the MIT license.

About

License:MIT License

Languages

Language:Python 51.4%Language:HTML 38.6%Language:SCSS 2.8%Language:Makefile 1.9%Language:Batchfile 1.8%Language:JavaScript 1.7%Language:CSS 1.7%