A not-so-straightforward Google App Engine for Python app template.

Main goals of this template:

  * Backend unit tests-ready with Testbed and Webtest
  * Frontend JS testing-ready (with Closure's Test Runner)
  * i18n support for both backend (Babel), Closure JS modules and Soy templates
  * CSS minification by class names renaming using Closure Stylesheets
  * An assembling/build/compilation (call it whatever you want) for a production-ready deployment

== To start from scratch ==

  # Clone the repo
  # Check for bootstrap vars in Makefile (VENV_DIR)
  # make bootstrap, follow instructions (e.g. source venv/bin/activate)
  # make t (should pass all tests)
  # mv README docs/from_scratch.txt
  # Check for other vars in Makefile (NONTESTS, PROJECT_NAME, etc.)
  # rm -rf .git && git init

For full usage you'll also need to have full source of Closure Library 
(e.g. linked so that base.js is in assets/js/closure-lib/closure/goog/),
latest compiler.jar + *.py scripts, closure-stylesheets.jar and SoyToJsSrcCompiler.jar.


== Workflow for frontend would go something like this: ==

1. Place Closure-namespaced JS files under "`assets/js/<name>/`"
  * add tests to "`assets/js/all_tests.js`"
  * you can then run tests individually, e.g. "`/js/notepad/notepad_test.html`" or all of them from "`/js/all_tests.html`"
  
  See http://closure-library.googlecode.com/svn/docs/index.html for API docs.

2. If you have Soy templates, do "`make soy`".

  This will compile "`templates/soy/*.soy`" into "`assets/js/<soy_filename>/soy.js`".
  See https://developers.google.com/closure/templates/docs/commands for template commands.

3. When you add new JS namespaces/modules/files, make sure to run "`make jsdeps`"

  Also, it's good to run jsdeps _after_ soy (soy templates normally contribute to the dependencies).

4. "`make js`" will compile the whole thing into "`assets/js/compiled.js`"
   
  To compile with i18n support, do this first:
    * check PROJECT_NAME var in Makefile
    * "`make js_extract_msg`". This will create locale/messages.xtb. Pass it on to the translation team.
    *  put translated files into locale/xx/LC_MESSAGES/messages.xtb
    * compile the whole thing with "`make js LOCALE=xx`"

5. For CSS, just do "`make css-debug`". 
  This will compile all "`assets/css/*.gss`" into "`assets/css/compiled_debug.css`".
  Production-compiled version with classes renaming is done running "`make css-compile`".

  See http://code.google.com/p/closure-stylesheets/ for details on GSS.

6. To assemble assets into production-ready folder (default is .assets-build),
do "`make assets`".

== Jinja2 templates ==

In dev mode, deps.js and goog/base.js would normally be referenced in a layout template.
When switching to production/compiled mode, those will be removed/replaced with compiled.js
(or modules) using tools/assetasm.py.

To compile dev templates into production-ready, do "`make templ`". If you're using
GSS classes in the templates too, don't forget to "`make css-map`", otherwise
those CSS classes will not be renamed in backnd templates (JS frontend always do).

To switch between dev/production templates use "`make 2dev`" and "`make 2prod`".

TODO: explain 
  * how that happens
  * how to use Closure modules

== Backend testing ==

All tests should be placed in tests/ dir. Just create a new file named xxx_test.py,
it'll be automatically found and ran when you "`make t`"

To run indivitual test files, do "`make t MOD=xxx_test`"

See tests/handlers_base_test.py for handlers/functional testing, 
tests/user_test.py for model testing.

For tests coverage, do "`make cov`". It'll display results in console and
generate HTML report: "open htmlcov/index.html".

Some resources on testing:
  * http://webtest.pythonpaste.org/en/latest/modules/webtest.html
  * https://developers.google.com/appengine/docs/python/tools/localunittesting

== Commands order ==

If you were to compile the whole thing (e.g. for deployment), here's
the "`make <target>`" commands order in which you could do it:

{{{
# dev:

# extract i18n messages from the backend
make babel_extract
# ONCE per locale: creates a new catalog
make babel_init LOCALE=en
# next updates should be run with 
# 'make babel_update LOCALE=en'.
# compiles catalogs for all languages
make babel_compile

# compile Soy templates.
make soy
# create deps.js file
make jsdeps
# this will also create cssmap_debug.js
make css-debug
## ready to roll with 'make s' now


# production-ready:

# prepare for JS compilation
make js_extract_msg LOCALE=en
make css-compiled
# compile all Closure JS app with advanced optimizations
make js LOCALE=en
# compile backend templates
make css-map # creates CSS renaming map in JSON format
# this will compile static assets too
make templ
## 'make 2prod s' if you wanna test it out manually
make deploy VER=myver
# override app ID with
# make deploy VER=myver APP_ID=myapp

# Always, additional flags are supported through
# make <target> FLAGS=...
}}} 


== make help ==

{{{
Use 'make <target>' where <target> is one of

  (t)est      to run unit testing. For a single module test use this:
              make t MOD=mod_name
  (cov)erage  to make test coverage report
  (s)erve     to start the app on development server
  (r)emote    to run Remote API shell

  bootstrap   to generate virtualenv in  (ONCE, at the very beginning) 
              and install needed packages from requirements.txt

  all-dev     After bootstrap and installing Closure Tools 
  all-prod    (see Makefile vars for customizing paths) it is wise 
              to check that at least minimum of the stack works

  == i18n and Babel

  1. babel_extract                     - extracts all translactions according to babel.cfg
  2. babel_init LOCALE=<your_locale>   - inits messages.pot (ONCE per language)
  3. translate locale/<lang>/LC_MESSAGES/messages.po
  4. babel_compile                     - compiles all translations
  - iterate: 
    * repeat step 1.
    * run 'make babel_update LOCALE=<your_locale>'
    * repeat step 3 and 4

  == Closure-related stuff

  css-debug        to compile *.gss into 
  css-compiled     to compile and minify *.gss (with classes renaming)
                   into 
  css-map          creates renaming map in JSON format.
                   Customize which files and how to compile with e.g.
                   GSS_FILES=style.gss FLAGS=--rename DEBUG
  jsdeps           to generate assets/js/deps.js
  (js)compile      to compile JS assets into assets/js/assets/js/compiled.js
                   OUTPUT_MODE=list to list dependencies
                   LOCALE=xx to compile with i18n
  js_extract_msg LOCALE=xx  
                   to extract goog.getMsg() in XTB format > locale/messages.xtb
  soy              to compile Soy templates. Override files to compile
                   with SOY_FILES=...

  == Deployment-related stuff

  templ       to assemble templates/*.html with tools/assetasm.py
  assets      to assemble assets/*
              Note take assetasm.py will also invoke assets 
              building when run with 'make templ'

  Alternative output for templ and assets targets works with
  OUTPUT_MODE={manifest|check}

  deploy      to deploy the app on production servers.
              You could do make deploy VER=myver FLAGS=-v
  2prod       will switch to production (build) version of assets
              and templates
  2dev        will switch to development version of assets
              and templates
  clean       removes .pyc, htmlcov, .coverage and CSS/JS compiled
              stuff
  clean-all   will also remove last assets and templates build

You can always use FLAGS='--whatever' as addition arguments to any target.
}}}