=================
Package Templates
=================

Werkzeug comes with a small script called `werkzeug-bootstrap`
which you can use to generate so called bootstrap code from
templates. Either from the templates that come with Werkzeug or your
own ones.


Getting Started
===============

To get started we can use one of the templates coming with Werkzeug.
Just call the `werkzeug-bootstrap` tool with the correct parameters::

    werkzeug-bootstrap -t default -c utf-8 myproject /path/to/project

This will now generate a new package `myproject` based on the template
`werkzeug_default` in ``/path/to/project`` with the charset `utf-8` for
the files and application.

If you specify a full canonical path for the `-t` parameter the data for
this path is used to generate the package, otherwise the template is looked
up in the builtin template folder.


Builtin Templates
=================

The following templates come with werkzeug:

`werkzeug_default`
    Simple package structure. Generates also a start script that fires up
    a wsgiref development server. The generated application will provide
    subclasses of the request and response objects with the specified
    charset, a minimal wsgi application with Werkzeug routing and a default
    view with additional information.


Writing Templates
=================

If you plan to create more than just one application with the same schema
you can create templates for that. Just create an folder somewhere and fill
it with defaults. Files that end with ``_tmpl`` are considered being werkzeug
`minitmpl`_ templates. If a filename contains the name `PACKAGE` it will be
replaced by the real package name.

Other special files:

``.INFO``
    a template that is displayed after template generation

``.DOCSTRING``
    a template for docstrings. Example:

    .. sourcecode:: python
    
        """
            <%= MODULE %>
            <%= '~' * len(MODULE) %>

        <%= make_textblock(4, 79, DOCSTRING) %>

            :copyright: <%= datetime.now().year %> by <%= AUTHOR %>.
        """

    The functions are explained below. You can then render the
    docstring from any template using ``<%= make_docstring(MODULE, 'foo') %>``
    where `MODULE` is the current module and ``'foo'`` the text for the
    docstring.

Global variables for all templates:

`AUTHOR`
    the author for the templates. Defaults to the loginname or on UNIX
    systems to the realname of the current user.

`PACKAGE`
    the name of the package (``my_project``)

`PACKAGE_PASCAL_CASE`
    the name of the package in pascal case (``MyProject``)

`FILE_ENCODING`
    the name of the encoding specified on the command line.

Global variables for templates that contain python code:

`MODULE`
    import name of the current module.

The following helper functions exist:

`datetime`
    just a reference to the datetime class

`make_textblock`
    Helper function to create aligned text blocks automatically.
    See the example for the ``.DOCSTRING`` template above.

`make_docstring`
    Helper function that renders a docstring using the template
    defined in ``.DOCSTRING``. See the example above.


.. _minitmpl: minitmpl.txt
