introduce webpack

.editorconfig

@@ -18,3 +18,6 @@ insert_final_newline = false
 
 [Makefile]
 indent_style = tab
+
+[*.js]
+indent_size = 2

.travis.yml

@@ -18,11 +18,11 @@ env:
   - TOXENV=project-tox-isort
   - TOXENV=project-tox-manifest
   - TOXENV=project-tox-pep257
-  - TOXENV=project-tox-py27
-  - TOXENV=project-tox-py35
-  - TOXENV=py27-project-develop
-  - TOXENV=py34-project-develop
-  - TOXENV=py35-project-develop
+  - TOXENV=project-tox-py27-npm-link
+  - TOXENV=project-tox-py35-npm-link
+  - TOXENV=py27-project-develop-npm-copy
+  - TOXENV=py34-project-develop-npm-copy
+  - TOXENV=py35-project-develop-npm-copy
 services:
   - postgresql
 addons:

README.rst

@@ -29,8 +29,8 @@ What makes this cookiecutter template special?
 * All Django settings can be easily configured for different environments like
   ``dev`` or ``prod`` using environment variables
 * Django third-party packages like django-braces, django-crispy-forms,
-  django-debug-toolbar, django-devserver, django-model-utils and
-  django-template-debug are already installed
+  django-debug-toolbar, django-model-utils and django-template-debug are
+  already installed
 * IPython for a powerfull Python and Django shell
 * A set of basic Django HTML templates is included
 * Includes a ``Makefile`` which helps with all the every-day tasks
@@ -87,7 +87,6 @@ Development Tools
 
 * `bumpversion <https://github.com/peritus/bumpversion>`_
 * `django-debug-toolbar <https://github.com/django-debug-toolbar/django-debug-toolbar>`_
-* `django-devserver <http://github.com/dcramer/django-devserver>`_
 
     * `sqlparse <https://github.com/andialbrecht/sqlparse>`_
     * `Werkzeug <http://werkzeug.pocoo.org/>`_

npm_install.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+#
+# Use a single node_modules directory for all tox envs.
+# Either copy or link the node_modules cache.
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+E_NOARGS=75
+NODE_CACHE=../../node_cache
+TOXTMP=$(pwd)
+
+function usage {
+    echo "Usage: `basename ${0}` [copy | link]"
+    exit ${E_NOARGS}
+}
+
+if [ $# -lt 1 ]; then
+    usage
+fi
+
+case $1 in
+    copy) CMD="cp -R";;
+    link) CMD="ln -s";;
+    *) usage;;
+esac
+
+if [ ! -d ${NODE_CACHE} ]; then
+    mkdir ${NODE_CACHE}
+    cp my-project/package.json ${NODE_CACHE}
+    cd ${NODE_CACHE}
+    npm install
+fi
+
+cd ${TOXTMP}/my-project
+${CMD} ../${NODE_CACHE}/node_modules .

tox.ini

@@ -1,5 +1,5 @@
 [tox]
-envlist = py27,py34,py35,pypy,docs,flake8,isort,project-tox-{docs,flake8,isort,manifest,pep257,py27,py35},{py27,py34,py35}-project-develop
+envlist = py27,py34,py35,pypy,docs,flake8,isort,project-tox-{docs,flake8,isort,manifest,pep257},project-tox-{py27,py35}-npm-link,{py27,py34,py35}-project-develop-npm-copy
 minversion = 2.1.0
 skipsdist = True
 
@@ -8,6 +8,8 @@ changedir = {envtmpdir}
 commands =
     pip install -r {toxinidir}/requirements/dev.pip
     cookiecutter --no-input -f {toxinidir}
+    npm-link: {toxinidir}/npm_install.sh link
+    npm-copy: {toxinidir}/npm_install.sh copy
     project-develop: {toxinidir}/test_develop.sh
     project-tox-docs: tox -c my-project/tox.ini -e docs
     project-tox-flake8: tox -c my-project/tox.ini -e flake8
@@ -19,7 +21,7 @@ commands =
 deps =
     project: tox==2.2.1
 setenv =
-    project-docs: SPHINXOPTS_LINKCHECK = "-Dlinkcheck_ignore='http(s)?://.*my-project.*'"
+    project-docs: SPHINXOPTS_LINKCHECK = "-Dlinkcheck_ignore='http(s)?://.*my-project.*','http(s)?://localhost.*'"
 
 [testenv:docs]
 basepython = python3.5

{{ cookiecutter.repo_name }}/MANIFEST.in

@@ -1,23 +1,35 @@
+include *.js
 include *.rst
+include *.json
 include LICENSE
 include Makefile
 include manage.py
+include MANIFEST.in
+include package.json
 include tox.ini
 
 exclude .bumpversion.cfg
 exclude .editorconfig
+exclude Procfile
 exclude pep257.sh
 
 recursive-include docs *.rst .gitkeep conf.py Makefile make.bat
 recursive-include requirements *.pip
 
 recursive-exclude * __pycache__
 recursive-exclude * *.py[co]
+graft bin
+graft docs
+prune docs/_build
 
 graft {{ cookiecutter.pkg_name }}
+graft {{ cookiecutter.pkg_name }}/webpack-stats-development.json
 graft tests
 
 prune envs
 prune {{ cookiecutter.pkg_name }}/.cache
+prune {{ cookiecutter.pkg_name }}/assets
 prune {{ cookiecutter.pkg_name }}/media
+prune {{ cookiecutter.pkg_name }}/media/.gitkeep
+prune {{ cookiecutter.pkg_name }}/static/bundles-development
 prune {{ cookiecutter.pkg_name }}/static_root

{{ cookiecutter.repo_name }}/Makefile

@@ -14,15 +14,16 @@ endef
 
 $(eval $(call CMDS, $(cmd)))
 
-.PHONY: help clean clean-build clean-docs clean-pyc clean-test cmd coverage coverage-html \
-    create-db develop docs isort migrate open-docs serve-docs runserver shell startapp test \
-    test-all test-upload upload
+.PHONY: help clean clean-build clean-bundles clean-docs clean-pyc clean-test cmd coverage \
+	coverage-html create-db develop docs isort migrate open-docs serve-docs runserver shell \
+	startapp test test-all test-upload upload
 
 help:
 	@echo "Please use 'make <target>' where <target> is one of"
-	@echo "  clean                    to remove all build, test, coverage and Python artifacts (does not remove backups)"
+	@echo "  clean                    to remove all build, test, coverage and Python artifacts as well as webpack development bundles (does not remove backups)"
 	@echo "  clean-backups            to remove backup files created by editors and Git"
 	@echo "  clean-build              to remove build artifacts"
+	@echo "  clean-bundles            to to remove webpack development bundles"
 	@echo "  clean-docs               to remove documentation artifacts"
 	@echo "  clean-pyc                to remove Python file artifacts"
 	@echo "  clean-test               to remove test and coverage artifacts"
@@ -48,8 +49,7 @@ help:
 	@echo "  test-upload              to upload a release to test PyPI using twine"
 	@echo "  upload                   to upload a release using twine"
 
-
-clean: clean-build clean-docs clean-test clean-pyc
+clean: clean-build clean-bundles clean-docs clean-test clean-pyc
 
 clean-backups:
 	find . -name '*~' -delete
@@ -61,6 +61,10 @@ clean-build:
 	rm -fr dist/
 	rm -fr *.egg-info
 
+clean-bundles:
+	rm -f {{ cookiecutter.pkg_name }}/webpack-stats-development.json
+	rm -fr {{ cookiecutter.pkg_name }}/static/bundles-development/
+
 clean-docs:
 	$(MAKE) -C docs clean BUILDDIR=$(BUILDDIR)
 
@@ -79,6 +83,7 @@ cmd:
 	@echo "  cmd                       Please use 'make cmd=<manage.py command>'"
 
 coverage:
+	npm run build-development
 	envdir envs/$(ENV) coverage run -m pytest $(TEST_ARGS) tests/
 	coverage report
 
@@ -102,6 +107,7 @@ develop:
 	pip install -U pip setuptools wheel
 	pip install -U -c requirements/constraints.pip -e .
 	pip install -U -c requirements/constraints.pip -r requirements/dev.pip
+	npm install
 
 dist: clean
 	python setup.py sdist bdist_wheel
@@ -137,6 +143,7 @@ startapp:
 	echo "Don't forget to add '{{ cookiecutter.pkg_name }}.apps."$$app_name".apps."$$app_name_title"Config' to INSTALLED_APPS in '{{ cookiecutter.pkg_name }}.config/settings/common.py'!"
 
 test:
+	npm run build-development
 	envdir envs/$(ENV) python -m pytest $(TEST_ARGS) tests/
 
 test-all:

{{ cookiecutter.repo_name }}/Procfile

@@ -0,0 +1,2 @@
+web: PYTHONUNBUFFERED=true make runserver PORT=8000
+webpack: npm run watch

{{ cookiecutter.repo_name }}/docs/conf.py

@@ -287,6 +287,8 @@
 #texinfo_no_detailmenu = False
 
 linkcheck_ignore = [
+    r'http(s)?://127.0.0.1.*',
+    r'http(s)?://localhost.*',
     # Uncomment the next line if the repository on GitHub is private.
     #r'https://github.com/{{ cookiecutter.github_account }}/{{ cookiecutter.repo_name }}.*',
 ]

{{ cookiecutter.repo_name }}/docs/deployment.rst

@@ -101,6 +101,27 @@ environment:
 
         $ echo "export ENV=prod" >> ~/.bashrc
 
+Create and fill the directories for user uploads and static files
+=================================================================
+
+Create the ``MEDIA_ROOT`` directory for user uploads. It must be outside of the
+:file:`site-packages` directory, so that new files can be created. Also set
+``MEDIA_URL`` to the URL serving the ``MEDIA_ROOT`` directory.
+
+If you serve the static files from inside the package you only have to set
+``STATIC_URL`` to the URL serving the ``STATIC_ROOT`` directory.
+
+If you use a CDN or Amazon S3 for serving static files, you have to download
+the package, extract the static files and copy them to the new location:
+
+::
+
+    $ tar -xzvf kmncms-0.1.0.tar.gz
+    $ cp -Rv {{ cookiecutter.pkg_name }}/static_root /home/www/static.example.com
+
+Put the URL serving this directory into ``STATIC_URL``.
+
+
 Migrate the database
 ====================
 
@@ -130,13 +151,3 @@ After that create a new superuser:
 ::
 
     $ envdir envs/prod python manage.py createsuperuser
-
-Create and fill the directories for user uploads and static files
-=================================================================
-
-Finally create the ``MEDIA_ROOT`` and ``STATIC_ROOT`` directories and collect
-the static files into the ``STATIC_ROOT`` directory:
-
-::
-
-    $ envdir envs/prod python manage.py collectstatic

{{ cookiecutter.repo_name }}/docs/installation.rst

@@ -111,6 +111,18 @@ versions to use:
     The first version passed to :program:`pyenv local` will be the main version
     used for the project.
 
+Node.js and npm
+---------------
+
+`Node.js <https://nodejs.org/>`_ is an asynchronous event driven framework,
+similar in design to and influenced by systems like Ruby's Event Machine or
+Python's Twisted. The `npm <https://www.npmjs.com/>`_ package manager is
+bundled with Node.js. Both will be used to install packages and take care of
+tasks for the frontend.
+
+Visit the `Node.js download page <https://nodejs.org/en/download/package-manager/>`_
+to figure out how to install both.
+
 PostgreSQL
 ----------
 
@@ -170,8 +182,8 @@ choose the default for all questions being asked during the initialzaion
 
     $ git-flow init
 
-Install Python packages
------------------------
+Install Python and JavaScript packages
+--------------------------------------
 
 First create a new virtualenv for the project using virtualenvwrapper:
 
@@ -186,7 +198,8 @@ Now you can install the packages for development:
     $ make develop
 
 You should run this command every time a requirement changes to update your
-development environment.
+development environment. It will install or update all required Python and
+JavaScript packages.
 
 Create the database
 -------------------
@@ -230,12 +243,37 @@ And to create a new Django superuser:
 Start the development webserver
 -------------------------------
 
-Finally start the development webserver:
+Finally start Django's development webserver:
 
 ::
 
     $ make runserver
 
+But this way `webpack <https://webpack.github.io/>`_ won't be started to build
+the JavaScript and CSS bundle. So use
+`Honcho <https://github.com/nickstenning/honcho>`_ to start both, runserver and
+webpack:
+
+::
+
+    $ honcho start
+
+Now open http://localhost:3000/ in your Browser. This is Django's development
+webserver, but it's proxied through `Browsersync
+<https://www.browsersync.io/>`_. If you open the URL in different browsers,
+Browsersync will synchronize them. If you click in one browser, the others will
+automatically do the same. It also watches all JavaScript, SASS and Python
+files. If any of these files is changed, Browsersync reloads all synchronized
+browsers. If you open http://localhost:3001/ you will see Browsersync's UI. You
+can use it to configure it, for example you can set a network throttle to
+emulate slow connections.
+
+If you don't want to use Honcho you can also start Django's development
+webserver and webpack with Browsersync manually. Of course you will need two
+terminals for that. In the first terminal start Django's development webserver:
+
+    $ make runserver
+
 To see the other targets available in the :file:`Makefile` simply run:
 
 ::

{{ cookiecutter.repo_name }}/docs/settings.rst

@@ -20,7 +20,7 @@ Both together control which settings are loaded and used.
     * - ``DJANGO_CONFIGURATION``
       - ``'Development'``
       - ``DJANGO_CONFIGURATION``
-      - | Name of the `django-configurations <https://github.com/jezdez/django-configurations>`_
+      - | Name of the `django-configurations <https://github.com/jazzband/django-configurations>`_
         | class you want to use.
     * - ``DJANGO_SETTINGS_MODULE``
       - ``'{{ cookiecutter.pkg_name }}.config.settings.dev'``
@@ -200,7 +200,6 @@ Development
 
 The default class for development is
 :py:class:`{{ cookiecutter.pkg_name }}.config.settings.dev.Development`.
-It uses `django-devserver <https://github.com/dcramer/django-devserver>`_.
 
 .. list-table::
     :header-rows: 1
@@ -219,25 +218,6 @@ It uses `django-devserver <https://github.com/dcramer/django-devserver>`_.
       - | A dictionary containing the
         | settings for all caches to be used
         | with Django.
-    * - ``DEVSERVER_ARGS``
-      - ``[]``
-      - ``DJANGO_DEVSERVER_ARGS``
-      - | Additional command line
-        | arguments to pass to the :command:`runserver`
-        | command (as defaults).
-        | Example environment value: ``--werkzeug``
-    * - ``DEVSERVER_MODULES``
-      - | ``['devserver.modules.sql.SQLRealTimeModule',``
-        | ``'devserver.modules.sql.SQLSummaryModule',``
-        | ``'devserver.modules.profile.ProfileSummaryModule',]``
-      - ``DJANGO_DEVSERVER_MODULES``
-      - | django-devserver modules. See
-        | `list of available modules <https://github.com/dcramer/django-devserver>`_.
-    * - ``DEVSERVER_TRUNCATE_SQL``
-      - ``True``
-      - ``DJANGO_DEVSERVER_TRUNCATE_SQL``
-      - | Enables SQL query truncation
-        | (used in ``SQLRealTimeModule``).
     * - ``EMAIL_BACKEND``
       - ``'django.core.mail.backends.console.EmailBackend'``
       - ``DJANGO_EMAIL_BACKEND``

{{ cookiecutter.repo_name }}/envs/dev/DJANGO_WEBPACK_LOADER

@@ -0,0 +1,6 @@
+{
+    'DEFAULT': {
+        'BUNDLE_DIR_NAME': 'bundles-development/',
+        'STATS_FILE': './{{ cookiecutter.pkg_name }}/webpack-stats-development.json',
+    }
+}