From 54f2bbbc50a8129cb1eb43377f48db38572e0e72 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 19 Jul 2008 21:36:53 +0000 Subject: Document project creation. --- docs/api/view.rst | 9 --- docs/index.rst | 1 + docs/narr/project.rst | 85 ++++++++++++++++++++++ repoze/bfg/paster.py | 17 +---- repoze/bfg/paster_template/+package+.ini_tmpl | 11 +++ repoze/bfg/paster_template/+package+/run.py_tmpl | 19 +++-- .../+package+/templates/mytemplate.pt | 2 +- repoze/bfg/paster_template/+package+/views.py | 5 -- repoze/bfg/paster_template/+package+/views.py_tmpl | 5 ++ repoze/bfg/paster_template/setup.py_tmpl | 9 ++- 10 files changed, 122 insertions(+), 41 deletions(-) delete mode 100644 docs/api/view.rst create mode 100644 docs/narr/project.rst create mode 100644 repoze/bfg/paster_template/+package+.ini_tmpl delete mode 100644 repoze/bfg/paster_template/+package+/views.py create mode 100644 repoze/bfg/paster_template/+package+/views.py_tmpl 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"> -

${greeting}

+

Welcome to ${project}

diff --git a/repoze/bfg/paster_template/+package+/views.py b/repoze/bfg/paster_template/+package+/views.py deleted file mode 100644 index 6947b577f..000000000 --- a/repoze/bfg/paster_template/+package+/views.py +++ /dev/null @@ -1,5 +0,0 @@ -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') diff --git a/repoze/bfg/paster_template/+package+/views.py_tmpl b/repoze/bfg/paster_template/+package+/views.py_tmpl new file mode 100644 index 000000000..d3824826a --- /dev/null +++ b/repoze/bfg/paster_template/+package+/views.py_tmpl @@ -0,0 +1,5 @@ +from repoze.bfg.template import render_template_to_response + +def my_view(context, request): + return render_template_to_response('templates/mytemplate.pt', + 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 """ ) -- cgit v1.2.3