Permalink
Browse files

Docs now in pretty good shape\!

  • Loading branch information...
1 parent 939b5f8 commit 21266ed8bf2a14152d6bf7cdf69fc8ed62644864 @smcmahon smcmahon committed Sep 29, 2012
Showing with 104 additions and 21 deletions.
  1. +6 −5 README.rst
  2. +3 −1 docs/HISTORY.txt
  3. +1 −1 setup.py
  4. +94 −14 src/templer/dexterity/templates/dexterity/DEXTERITY_README.rst_tmpl
View
@@ -64,9 +64,9 @@ Notes
Egg Directories
---------------
-In order to support local commands, templer will create Paste,
-PasteDeploy and PasteScript eggs inside your product. These are only needed
-for development. You can and should remove them from your add-on distribution.
+In order to support local commands, templer will create Paste, PasteDeploy and
+PasteScript eggs inside your product. These are only needed for development.
+You can and should remove them from your add-on distribution.
Also remove::
@@ -80,9 +80,10 @@ Errors
If you hit and error like this::
- pkg_resources.DistributionNotFound: plone.app.relationfield: Not Found for: my.product (did you run python setup.py develop?)
+ pkg_resources.DistributionNotFound: plone.app.relationfield:
+ Not Found for: my.product (did you run python setup.py develop?)
-when attempting to run `paster addcontent`, then you need to ensure that
+when attempting to run `paster add`, then you need to ensure that
Paster knows about all the relevant eggs from your buildout.
Add `${instance:eggs}` to your `paster` section in your buildout, thusly::
View
@@ -4,4 +4,6 @@ Changelog
1.0a1
-----
-* Mostly derived from zopeskel.dexterity; see that project's repository for earlier history.
+* Mostly derived from zopeskel.dexterity; see that project's repository for
+ earlier history.
+ [smcmahon]
View
@@ -18,7 +18,7 @@
open(os.path.join("docs", "HISTORY.txt")).read(),
# Get more strings from http://pypi.python.org/pypi?%3Aaction=list_classifiers
classifiers=[
- "Development Status :: 4 - Development",
+ "Development Status :: 3 - Alpha",
"Framework :: Zope2",
"Framework :: Zope3",
"Framework :: Plone",
@@ -1,8 +1,9 @@
-Congratulations! If you're reading this document, you have created a Python
+**Congratulations!** If you're reading this document, you have created a Python
package meant to support development of Dexterity content types and behaviors.
-This document introduces you to use to the package skeleton.
+This document introduces you to use of the package skeleton. *If you're using
+templer.dexterity for the first time, you'll want to read every word.*
-Adding the package to your Plone installation
+Adding the Package to Your Plone Installation
=============================================
You have probably created this package in a ./src subdirectory of your
@@ -69,7 +70,7 @@ And, a behavior::
As when you ran templer to create this package, templer will ask you the
questions that must be answered to create the new skeleton.
-Guide to the package skeleton
+Guide to The Package Skeleton
=============================
At the top level of your package (where this document) resides, you will find
@@ -96,17 +97,23 @@ __init__.py
Package initialization machinery. When you first create
this package, it will contain some i18n setup.
-locales
+locales : directory
A directory for translations of your package messages.
-profiles
+profiles : directory
Generic Setup profiles for this package
-profiles : default
+profiles/default : directory
The default setup profile, often the only one. This will contain
information on package dependencies and content type factory
type information.
+profiles/default/types.xml
+ An empty Generic Setup content types list. List new types here.
+
+profiles/default/metadata.xml
+ Specify package dependencies and profile version number here.
+
static
Use the static directory for non-template browser resources like images,
stylesheets and JavaScript. See the README.txt in that directory.
@@ -127,20 +134,93 @@ tests.py
run by the test runner. When your package is first created, all
this does is run the integration doc tests.
+Guide to Content Type Skeletons
+===============================
+When you use the `add` local command to add a content-type skeleton,
+it will create or modify the following files and directories:
-Guide to content type skeletons
-===============================
+content_class_templates : directory
+ Put templates for your new type here
+
+content_class_templates/sampleview.pt
+ A sample view template for your new content type
+
+models : directory
+ One option for specifying your content type's field schema
+ is to use a supermodel XML file. This is the place to put it.
+
+models/content_class.xml
+ An empty supermodel XML file for the content type. If you've
+ been developing your content type TTW, you may export the
+ model file and use it to replace this.
+
+profiles/default/types.xml
+ Your new type is automatically added to this type list.
+
+profiles/default/types : directory
+ If it didn't previously exist, this directory is created to
+ contain factory-type information specifications for content
+ types.
+
+profiles/default/types/content_class.xml
+ A plain vanilla Generic Setup factory-type information XML
+ specification file. You'll nearly certainly edit this.
+
+ One option for specifying your field schema is to download
+ this file via the Dexterity control panel after specifying
+ fields through-the-web.
+
+content_class.py
+ Add Python functionality here. This file contains a bare-bones
+ interface definition, class declaration, and browser view class
+ declaration (ties template to type).
+
+ If you want to specify your field schema via Zope schema class
+ attributes, do so here.
-Content Type testing
---------------------
+content_class.txt
+ A sample DocTest file for your content type. Unless you've your
+ own preferred testing mechanism, write tests for your content
+ type functionality here.
-Guide to behavior skeletons
+
+Guide to Behavior Skeletons
===========================
-Behavior testing
-----------------
+Adding a behavior skeleton makes a smaller set of changes:
+
+behavior_filename.py
+ Create your behavior functionality here. This file contains
+ the schema definitions and implementations for the behavior.
+
+configure.zcml
+ This file is altered to add the ZCML wiring to let Zope and
+ Dexterity runtime know about your behavior.
+
+Running Tests
+=============
+
+To run tests, you'll first need the Zope testrunner installed as
+part of your buildout. If you've used the Unified Installer to set
+up your buildout, that's included in the develop.cfg. If not, add::
+
+ [test]
+ recipe = zc.recipe.testrunner
+ defaults = ['--auto-color', '--auto-progress']
+
+ eggs =
+ ${buildout:eggs}
+ list of extra test-support packages
+
+And add `[test]` to your parts list.
+
+Run buildout to get the parts in place, then you'll be able to
+run all your package tests with the command::
+
+ bin/test -s ${namespace_package}.${package}
+Executed from your buildout directory.
Before Package Distribution or Deployment
=========================================

0 comments on commit 21266ed

Please sign in to comment.