Permalink
Browse files

README

  • Loading branch information...
1 parent d90b119 commit f9d19afd8ad6b6f3e531d6dade4a634cab147a77 @shazow committed Sep 30, 2011
Showing with 88 additions and 2 deletions.
  1. +1 −0 .gitignore
  2. +87 −2 README.rst
View
@@ -3,3 +3,4 @@
*.egg-info
/dist
/build
+/tmp
View
@@ -1,3 +1,88 @@
+An unofficial scaffolding for Pyramid. Recommended for advanced Pyramid or Pylons developers.
+
+Highlights
+==========
+
+* Decoupled components: Use the project pieces independently of the web component.
+* Inspired by the original Pylons project structure and the ``pyramid_routesalchemy`` paster template.
+* Includes a reasonable CSS reset and an inheritance-based Mako template setup.
+* SQLAlchemy-compatible but not setup out of the box.
+* No hidden code in ``__init__.py`` files.
+* All the web-related setup happens in ``{{project}}/web/environment.py``
+
+
+Usage
+=====
+
+Install: ::
+
+ $ pip install https://github.com/shazow/pyramid_scaffolds_decoupled/tarball/master
+ $ paster create --list-templates
+ Available templates:
+ basic_package: A basic setuptools-enabled package
+ ...
+ > pyramid_decoupled: Decouple web-specific code from the rest (models, library api, etc).
+ pyramid_routesalchemy: pyramid SQLAlchemy project using url dispatch (no traversal)
+ pyramid_starter: pyramid starter project
+ ...
+
+Create a project: ::
+
+ $ paster create -t pyramid_decoupled foo
+ $ cd foo
+ $ find . | manualediting
+ ./CHANGES.txt
+ ./MANIFEST.in
+ ./README.txt
+ ./development.ini
+ ./production.ini
+ ./foo
+ ./foo/__init__.py
+ ./foo/lib
+ ./foo/lib/__init__.py
+ ./foo/lib/helpers.py <- Available as 'h' in templates.
+ ./foo/models
+ ./foo/models/__init__.py <- Unopinionated model submodule.
+ ./foo/tests
+ ./foo/tests/__init__.py
+ ./foo/web
+ ./foo/web/__init__.py
+ ./foo/web/environment.py <- Setup like routes lives here.
+ ./foo/web/static
+ ./foo/web/static/css
+ ./foo/web/static/images
+ ./foo/web/static/js
+ ./foo/web/templates
+ ./foo/web/templates/base.mako
+ ./foo/web/templates/index.mako
+ ./foo/web/views
+ ./foo/web/views/__init__.py
+ ./foo/web/views/index.py
+ ./setup.cfg
+ ./setup.py
+
+
+Suggested Structure
+-------------------
+
+I'll usually build a context-insensitive API library in ``{{project}}/api/``, so
+that I can do things like: ::
+
+ >>> import foo.api
+ >>> foo.api.account.change_password(user='foo', password='bar')
+ >>> r = foo.api.inventory.list(limit=20)
+
+The ``api`` generally uses the model to do things.
+
+This way, most of the business logic lives in the API library and is easily used
+by daemons, tests, or web views.
+
+
TODO
-----
-Write this readme.
+====
+
+* Fix ``{{project}}/tests`` (still has ``pyramid_routesalchemy`` code)
+* Add an out-of-the-box SQLAlchemy setup
+* Maybe add optional TurboMail example?
+* Useful example for the api structure
+* More documentation

0 comments on commit f9d19af

Please sign in to comment.