Document project creation.

9 files changed, 118 insertions, 37 deletions

diff --git a/docs/api/view.rst b/docs/api/view.rst
deleted file mode 100644
index 943932ddf..000000000
--- a/docs/api/view.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-.. _view_module:
-
-:mod:`repoze.bfg.view`
-------------------------
-
-.. currentmodule:: repoze.bfg.view
-
-.. autoclass:: ViewFactory
-   :members:
diff --git a/docs/index.rst b/docs/index.rst
index d295c05d3..380f9128a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,6 +13,7 @@ Narrative documentation in chapter form explaining how to use
    :maxdepth: 2
 
    narr/introduction
+   narr/project
    narr/views
    narr/templates
    narr/models
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
new file mode 100644
index 000000000..651f505c5
--- /dev/null
+++ b/docs/narr/project.rst
@@ -0,0 +1,85 @@
+Starting a ``repoze.bfg`` Project
+=================================
+
+To start a ``repoze.bfg`` project, use the ``paster create``
+facility::
+
+  $ paster create -t bfg
+  Selected and implied templates:
+    repoze.bfg#bfg  repoze.bfg starter project
+
+  Enter project name: myproject
+  Variables:
+    egg:      myproject
+    package:  myproject
+    project:  myproject
+  Creating template bfg
+  Creating directory ./myproject
+    Recursing into +package+
+      Creating ./myproject/myproject/
+      Copying __init__.py to ./myproject/myproject/__init__.py
+      Copying configure.zcml to ./myproject/myproject/configure.zcml
+      Copying models.py to ./myproject/myproject/models.py
+      Copying run.py_tmpl to ./myproject/myproject/run.py
+      Recursing into templates
+        Creating ./myproject/myproject/templates/
+        Copying mytemplate.pt to ./myproject/myproject/templates/mytemplate.pt
+      Copying views.py_tmpl to ./myproject/myproject/views.py
+    Copying +package+.ini_tmpl to ./myproject/myproject.ini
+    Copying CHANGES.txt_tmpl to ./myproject/CHANGES.txt
+    Copying README.txt_tmpl to ./myproject/README.txt
+    Copying ez_setup.py to ./myproject/ez_setup.py
+    Copying setup.py_tmpl to ./myproject/setup.py
+  Running /Users/chrism/projects/repoze-devel/bfg/bin/python setup.py egg_info
+
+The project will be created in a directory named ``myproject``.  That
+directory is a directory from which a Python setuptools *distribution*
+can be created.  THe ``setup.py`` file in that directory can be used
+to distribute your application, or install your application for
+deployment or development. A sample PasteDeploy ``.ini`` file named
+``myproject.ini`` will also be created in the project directory.  You
+can use this to run your application.
+
+The main ``myproject`` contains an additional subdirectory (also named
+``myproject``) representing a Python pakckage which holds very simple
+bfg sample code.  This is where you'll edit your application's Python
+code and templates.
+
+Installing your Newly Created Project for Development
+-----------------------------------------------------
+
+Using your favorite Python interpreter (using a virtualenv suggested
+in order to get isolation), invoke the following command when inside
+the project directory against the generated ``setup.py``::
+
+  $ python setup.py develop
+   ...
+   Finished processing dependencies for myproject==0.1
+
+This will install your application 's package into the interpreter so
+it can be found and run under a webserver.
+
+Runnning The Project Application
+--------------------------------
+
+Once the project is installed for development, you can run it using
+the ``paster serve`` command against the generated ``myproject.ini``
+configuration file::
+
+  $ paster serve myproject/myproject.ini
+  Starting server in PID 16601.
+  serving on 0.0.0.0:5432 view at http://127.0.0.1:5432
+
+It will listen on port 5432.  If you visit the unchanged sample
+application using a browser (e.g. http://localhost:5432/), you will
+see the following::
+
+  Welcome to myproject
+
+.. note:: During development, it's often useful to run ``paster serve``
+   using its ``--reload`` option.  When any Python module your project
+   uses, changes, it will restart the server, which makes development
+   easier, as changes to Python code under ``repoze.bfg`` is not put
+   into effect until the server restarts.
+
+
diff --git a/repoze/bfg/paster.py b/repoze/bfg/paster.py
index 8a1ab028d..f574a1862 100644
--- a/repoze/bfg/paster.py
+++ b/repoze/bfg/paster.py
@@ -1,21 +1,8 @@
-from paste.script.templates import Template, var
+from paste.script.templates import Template
 from paste.util.template import paste_script_template_renderer
 
-vars = [
-    var('version', '0.1'),
-    var('description', 'One-line description of the package'),
-#    var('long_description', 'Multi-line description (in reST)'),
-#    var('keywords', 'Space-separated keywords/tags'),
-#    var('author', 'Author name'),
-#    var('author_email', 'Author email'),
-#    var('url', 'URL of homepage'),
-#    var('license_name', 'License name'),
-    var('zip_safe', 'True/False: if the package can be distributed as a .zip file',
-        default=False),
-]
-
 class BFGProjectTemplate(Template):
     _template_dir = 'paster_template'
     summary = 'repoze.bfg starter project'
-    vars = vars
+    vars = []
     template_renderer = staticmethod(paste_script_template_renderer)
diff --git a/repoze/bfg/paster_template/+package+.ini_tmpl b/repoze/bfg/paster_template/+package+.ini_tmpl
new file mode 100644
index 000000000..9bb03718c
--- /dev/null
+++ b/repoze/bfg/paster_template/+package+.ini_tmpl
@@ -0,0 +1,11 @@
+[DEFAULT]
+debug = true
+
+[app:main]
+use = egg:{{project}}#make_app
+
+[server:main]
+use = egg:PasteScript#cherrypy
+host = 0.0.0.0
+port = 5432
+numthreads = 4
diff --git a/repoze/bfg/paster_template/+package+/run.py_tmpl b/repoze/bfg/paster_template/+package+/run.py_tmpl
index 2d221ead3..f8228d30a 100644
--- a/repoze/bfg/paster_template/+package+/run.py_tmpl
+++ b/repoze/bfg/paster_template/+package+/run.py_tmpl
@@ -1,8 +1,13 @@
-from paste import httpserver
+def make_app(global_config, **kw):
+    # paster app config callback
+    from repoze.bfg import make_app
+    from {{project}}.models import get_root
+    import {{ project}}
+    app = make_app(get_root, {{project}})
+    return app
 
-from repoze.bfg import make_app
-from {{project}}.models import get_root
-import {{project}}
-
-app = make_app(get_root, {{project}})
-httpserver.serve(app, host='0.0.0.0', port='5432')
+if __name__ == '__main__':
+    from paste import httpserver
+    app = make_app(None)
+    httpserver.serve(app, host='0.0.0.0', port='5432')
+    
diff --git a/repoze/bfg/paster_template/+package+/templates/mytemplate.pt b/repoze/bfg/paster_template/+package+/templates/mytemplate.pt
index becc5e9ec..a7affedf9 100644
--- a/repoze/bfg/paster_template/+package+/templates/mytemplate.pt
+++ b/repoze/bfg/paster_template/+package+/templates/mytemplate.pt
@@ -2,6 +2,6 @@
      xmlns:tal="http://xml.zope.org/namespaces/tal">
 <head></head>
 <body>
-  <h1>${greeting}</h1>
+  <h1>Welcome to ${project}</h1>
 </body>
 </html>
diff --git a/repoze/bfg/paster_template/+package+/views.py b/repoze/bfg/paster_template/+package+/views.py_tmpl
index 6947b577f..d3824826a 100644
--- a/repoze/bfg/paster_template/+package+/views.py
+++ b/repoze/bfg/paster_template/+package+/views.py_tmpl
@@ -2,4 +2,4 @@ from repoze.bfg.template import render_template_to_response
 
 def my_view(context, request):
     return render_template_to_response('templates/mytemplate.pt',
-                                       greeting = 'hello world')
+                                       project = '{{project}}')
diff --git a/repoze/bfg/paster_template/setup.py_tmpl b/repoze/bfg/paster_template/setup.py_tmpl
index 9e3db8500..278153de8 100644
--- a/repoze/bfg/paster_template/setup.py_tmpl
+++ b/repoze/bfg/paster_template/setup.py_tmpl
@@ -1,5 +1,3 @@
-__version__ = '{{version}}'
-
 import os
 
 from ez_setup import use_setuptools
@@ -12,7 +10,7 @@ README = open(os.path.join(here, 'README.txt')).read()
 CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
 
 setup(name='{{project}}',
-      version=__version__,
+      version='0.1',
       description='{{project}}',
       long_description=README + '\n\n' +  CHANGES,
       classifiers=[
@@ -24,6 +22,9 @@ setup(name='{{project}}',
         "Topic :: Internet :: WWW/HTTP :: WSGI",
         "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
         ],
+      author='',
+      author_email='',
+      url='',
       keywords='web wsgi bfg zope',
       packages=find_packages(),
       include_package_data=True,
@@ -37,7 +38,7 @@ setup(name='{{project}}',
       test_suite="{{project}}.tests",
       entry_points = """\
       [paste.app_factory]
-      {{project}} = {{project}}.run:make_app
+      make_app = {{project}}.run:make_app
       """
       )