[Checkins] SVN: grok/trunk/doc/ Tidying up the ref docs.
Kevin Teague
kevin at bud.ca
Sun Mar 8 16:29:45 EDT 2009
Log message for revision 97668:
Tidying up the ref docs.
Changed:
U grok/trunk/doc/.static/grok.css
U grok/trunk/doc/reference/components.rst
U grok/trunk/doc/reference/directives.rst
-=-
Modified: grok/trunk/doc/.static/grok.css
===================================================================
--- grok/trunk/doc/.static/grok.css 2009-03-08 18:06:51 UTC (rev 97667)
+++ grok/trunk/doc/.static/grok.css 2009-03-08 20:29:45 UTC (rev 97668)
@@ -644,7 +644,6 @@
}
.section blockquote {
- border: solid 2px #eeeeee;
margin: 0em;
padding: 0.5em;
}
Modified: grok/trunk/doc/reference/components.rst
===================================================================
--- grok/trunk/doc/reference/components.rst 2009-03-08 18:06:51 UTC (rev 97667)
+++ grok/trunk/doc/reference/components.rst 2009-03-08 20:29:45 UTC (rev 97668)
@@ -265,7 +265,7 @@
.. class:: grok.OrderedContainer
Base class for an OrderedContainer. OrderedContainer inherits from
- Container and supports the API.
+ Container and supports the same interface.
.. method:: updateOrder(order)
@@ -283,8 +283,9 @@
:class:`grok.Indexes`
=====================
-Indexes are data structures that provide a way of quickly finding
-data model objects.
+Indexes are containers for holding a set of indexes. An index is
+a data structures that provides a way of quickly finding a data objects.
+A single index can be of either `Field`, `Text`, or `Set`.
.. class:: grok.Indexes
@@ -299,7 +300,6 @@
.. code-block:: python
import grok
- from grok import index
from zope.interface import Interface
from zope import schema
@@ -313,7 +313,7 @@
grok.site(Herd)
grok.context(IMammoth)
- full_name = index.Text()
+ full_name = grok.index.Text()
class Mammoth(grok.Model):
grok.implements(IMammoth)
@@ -338,10 +338,7 @@
# mammoths would be a list containing 'Manfred Mammoth' and 'Joe Mammoth'
# but not 'Marty the Wooly'
-Indexes can index on multiple fields. A single index can be of either `Field`,
-`Text`, or `Set`.
-
Adapters
~~~~~~~~
@@ -689,7 +686,10 @@
:class:`grok.View`
==================
-View components provide context and request attributes.
+Views handle interactions between the user and the model. The are constructed
+with context and request attributes, are responsible for providing a
+response. The request attribute in a View will always be for a normal
+HTTP Request.
The determination of what View gets used for what Model is made by walking the
URL in the HTTP Request object sepearted by the / character. This process is
@@ -977,30 +977,30 @@
Specialized View that responds to XML-RPC.
-The grok.require decorator can be used to protect methods with a permission.
-
.. class:: grok.XMLRPC
Base class for XML-RPC methods.
**Example 1: Create a public and a protected XML-RPC view.**
+The grok.require decorator can be used to protect methods with a permission.
+
.. code-block:: python
- from zope import interface
-
- class FooXMLRPC(grok.XMLRPC):
- """
- The methods in this class will be available as XML-RPC methods.
-
- http://localhost/say will return 'Hello world!' encoded in XML-RPC.
- """
- grok.context(interface.Interface)
+ import grok
+ import zope.interface
+
+ class MammothRPC(grok.XMLRPC):
+ grok.context(zope.interface.Interface)
- def say(self):
- return 'Hello world!'
+ def stomp(self):
+ return 'Manfred stomped.'
+ @grok.require('zope.ManageContent')
+ def dance(self):
+ return 'Manfred doesn\'t like to dance.'
+
:class:`grok.Traverser`
=======================
Modified: grok/trunk/doc/reference/directives.rst
===================================================================
--- grok/trunk/doc/reference/directives.rst 2009-03-08 18:06:51 UTC (rev 97667)
+++ grok/trunk/doc/reference/directives.rst 2009-03-08 20:29:45 UTC (rev 97668)
@@ -13,68 +13,23 @@
environment of a module. (For example, a view will be automatically associated
with a model if the association can be made unambigously.)
-If no default can be assumed for a value, grok will explicitly tell you what is
-missing and how you can provide a default or explicit assignment for the value
-in question.
+If no default can be assumed for a value, grok will explicitly tell you what
+is missing and how you can provide a default or explicit assignment for
+the value in question.
Core directives
~~~~~~~~~~~~~~~
-:func:`grok.context` -- declare the context for views, adapters, etc.
-=====================================================================
+Core directives are applicable to any type of component.
-.. function:: grok.context(*class_or_interface)
+:func:`grok.name`
+=================
- A class or module level directive to indicate the context for
- something (class or module) in the same scope.
+Associate a component with a name.
- When used on module level, it will set the context for all views,
- adapters, etc. in that module. When used on class level, it will set
- the context for that particular class.
+Name is a unique identifier in the form of a string. The names of
+Containers, Models and Views are used to compose the URLs of the application.
- With Grok contexts are set automatically for some objects, if they are
- unambigous. For example a :class:`grok.View` will get the only
- :class:`grok.Application` or :class:`grok.Model` class as context,
- iff there exists exactly one in the same module. If there are more
- possible contexts or you want to set a type (class/interface) from
- another module as context, than the one choosen by default, then you
- have to call :func:`grok.context` explicitly.
-
-**Example: Declare a component depends upon a class or interface**
-
-Here the :func:`grok.context` directive indicates that the :class:`Index`
-View applies to the context of a :class:`Mammoth` instance, and not instances
-of :class:`Cave`. By declaring the class or interface with :func:`grok.context`
-for an object, you are stating that your object depends upon the methods
-and attributes of that context.
-
-.. code-block:: python
-
- import grok
-
- class Mammoth(grok.Model):
- hair = 'Wooly'
-
- class Cave(grok.Model):
- texture = 'rough'
-
- class Index(grok.View):
- grok.context(Mammoth)
-
- def render(self):
- # self.context will always have the interface of a Mammoth object,
- # since this view declares that it depends upon the context of a
- # Mammoth class.
- return "It feels %s" % self.context.hair
-
-.. seealso::
-
- :class:`grok.View`, :class:`grok.Adapter`, :class:`grok.MultiAdapter`
-
-
-:func:`grok.name` -- associate a component with a name
-======================================================
-
.. function:: grok.name(name)
A class level directive used to associate a component with a single
@@ -110,25 +65,37 @@
:class:`grok.View`
-:func:`grok.title` -- succinct description
-==========================================
+:func:`grok.title`
+==================
+Succint description.
+
+This directive is not commonly used, but along with :func:`grok.description`
+can help provide more information about a component.
+
.. function:: grok.title(title)
A descriptive title for a component.
-:func:`grok.description` -- longer description
-==============================================
+:func:`grok.description`
+========================
+Longer description.
+
+This directive is not commonly used, but along with :func:`grok.title`
+can help provide more information about a component.
+
.. function:: grok.description(description)
A longer description for a component.
-:func:`grok.implements` -- indicate, that a class implements an interface
-=========================================================================
+:func:`grok.implements`
+=======================
+Declare that a class implements an interface.
+
.. function:: grok.implements(*interfaces)
A class level directive to declare one or more `interfaces`, as
@@ -194,9 +161,11 @@
and `zope.interface.verify.verifyObject(interface, object)` to verify if
a class or object actually implements or provides a specific interface.
-:func:`grok.provides` -- disambiguate which interface is registered
-===================================================================
+:func:`grok.provides`
+=====================
+Disambiguate which interface is registered.
+
.. function:: grok.provides(interface)
Explicitly specify with which interface a component will be
@@ -209,9 +178,16 @@
:func:`grok.implements`
-:func:`grok.direct` -- specify that the class should be the component
-=====================================================================
+:func:`grok.direct`
+===================
+Specify that the class should be the component.
+
+Typically a class implements an interface, and the class is used as a
+factory to construct objects that provide that interface. With this
+directive, the class object can by used to provide the interface
+directly without constructing additional instance objects.
+
.. function:: grok.direct()
Specify whether the class should be used for the component
@@ -222,28 +198,11 @@
utility, or an instance of it.
-:func:`grok.adapts` -- declare that a class adapts certain objects
-==================================================================
+:func:`grok.baseclass`
+======================
-In the case of a simple adapter which only requires a single object
-for adapation, the :func:`grok.context` directive is used to declare
-the interface or class the adapter is for. It is only necessary to use
-:func:`grok.adapts` to declare the adapation requirements for a multi adapter.
+Declare a class as a base class.
-.. function:: grok.adapts(*classes_or_interfaces)
-
- A class-level directive to declare that a class adapts objects of
- the classes or interfaces given in `\*classes_or_interfaces`.
-
- This directive accepts several arguments.
-
- It works much like the :mod:`zope.component.`:func:`adapts()`,
- but you do not have to make a ZCML entry to register the adapter.
-
-
-:func:`grok.baseclass` -- declare a class as base
-=================================================
-
.. function:: grok.baseclass()
A class-level directive without argument to mark something as a base
@@ -279,9 +238,11 @@
Utility directives
~~~~~~~~~~~~~~~~~~
-:func:`grok.global_utility` -- register a global utility
-========================================================
+:func:`grok.global_utility`
+===========================
+Register a global utility.
+
.. function:: grok.global_utility(factory[, provides=None[, name=u'']])
A module level directive to register a global utility.
@@ -338,9 +299,11 @@
:func:`grok.implements`
-:func:`grok.local_utility` -- register a local utility
-======================================================
+:func:`grok.local_utility`
+==========================
+Register a local utility.
+
.. function:: grok.local_utility(factory[, provides=None[, name=u''[, setup=None[, public=False[, name_in_container=None]]]]])
A class level directive to register a local utility.
@@ -405,13 +368,100 @@
:func:`grok.global_utility`, :class:`grok.LocalUtility`
+Adapter directives
+~~~~~~~~~~~~~~~~~~
+:func:`grok.context`
+====================
+
+Declare the context for views, adapters, etc.
+
+Adapters are composed from another object, this object is called the
+context object. This directive specifies the class or interface that
+this object must provide.
+
+If the context declaration is not supplied, then Grok will set the context
+to the an Application, Container or Model class in module, as long as there
+is only one class of that type in the module.
+
+.. function:: grok.context(*class_or_interface)
+
+ A class or module level directive to indicate the context for
+ something (class or module) in the same scope.
+
+ When used on module level, it will set the context for all views,
+ adapters, etc. in that module. When used on class level, it will set
+ the context for that particular class.
+
+ With Grok contexts are set automatically for some objects, if they are
+ unambigous. For example a :class:`grok.View` will get the only
+ :class:`grok.Application` or :class:`grok.Model` class as context,
+ iff there exists exactly one in the same module. If there are more
+ possible contexts or you want to set a type (class/interface) from
+ another module as context, than the one choosen by default, then you
+ have to call :func:`grok.context` explicitly.
+
+**Example: Declare a component depends upon a class or interface**
+
+Here the :func:`grok.context` directive indicates that the :class:`Index`
+View applies to the context of a :class:`Mammoth` instance, and not instances
+of :class:`Cave`. By declaring the class or interface with :func:`grok.context`
+for an object, you are stating that your object depends upon the methods
+and attributes of that context.
+
+.. code-block:: python
+
+ import grok
+
+ class Mammoth(grok.Model):
+ hair = 'Wooly'
+
+ class Cave(grok.Model):
+ texture = 'rough'
+
+ class Index(grok.View):
+ grok.context(Mammoth)
+
+ def render(self):
+ # self.context will always have the interface of a Mammoth object,
+ # since this view declares that it depends upon the context of a
+ # Mammoth class.
+ return "It feels %s" % self.context.hair
+
+.. seealso::
+
+ :class:`grok.View`, :class:`grok.Adapter`, :class:`grok.MultiAdapter`
+
+
+:func:`grok.adapts`
+===================
+
+Declare that a class adapts certain objects.
+
+In the case of a simple adapter which only requires a single object
+for adapation, the :func:`grok.context` directive is used to declare
+the interface or class the adapter is for. It is only necessary to use
+:func:`grok.adapts` to declare the adapation requirements for a multi adapter.
+
+.. function:: grok.adapts(*classes_or_interfaces)
+
+ A class-level directive to declare that a class adapts objects of
+ the classes or interfaces given in `\*classes_or_interfaces`.
+
+ This directive accepts several arguments.
+
+ It works much like the :mod:`zope.component.`:func:`adapts()`,
+ but you do not have to make a ZCML entry to register the adapter.
+
+
Security directives
~~~~~~~~~~~~~~~~~~~
-:func:`grok.require` -- declare a permission
-============================================
+:func:`grok.require`
+====================
+Declare a permission.
+
.. function:: grok.require(permission)
A class level directive used to protect a View by requiring a
@@ -441,9 +491,11 @@
Component registry directives
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-:func:`grok.site` -- specify the local component registry to use for indexes
-============================================================================
+:func:`grok.site`
+=================
+Specify the local component registry to use for indexes.
+
A class level directive used in `grok.Indexes` sub-classes to define
in which local component registry the indexes should be located.
@@ -462,9 +514,11 @@
View directives
~~~~~~~~~~~~~~~
-:func:`grok.layer` -- declare the layer for the view
-====================================================
+:func:`grok.layer`
+==================
+Declare the layer for the view.
+
.. function:: grok.layer(layer)
Declare the layer for the view.
@@ -473,9 +527,11 @@
grok.View. This directive can only be used on class level.
-:func:`grok.skin` -- declare this layer as a named skin
-=======================================================
+:func:`grok.skin`
+=================
+Declare this layer as a named skin.
+
.. function:: grok.skin(skin)
Declare this layer as a named skin.
@@ -483,9 +539,11 @@
This directive can only be used on class level.
-:func:`grok.template` -- specify a template name
-====================================================
+:func:`grok.template`
+=====================
+Specify a template name.
+
A class level directive used to specify the template to be rendered
for the View when no render method is defined. This allows you to
override the default convention of naming the template file with the same
@@ -501,9 +559,11 @@
:func:`grok.templatedir`
-:func:`grok.templatedir` -- specify the templates directory
-===========================================================
+:func:`grok.templatedir`
+========================
+Specify the templates directory.
+
A module level directive used to specify the directory where Grok
should look for template files.
@@ -521,9 +581,11 @@
:func:`grok.template`
-:func:`grok.order` -- specify ordering of components
-====================================================
+:func:`grok.order`
+==================
+Specify ordering of components.
+
Ordering is typically used in Viewlets to determine the order in which
they are displayed.
@@ -547,9 +609,11 @@
URL Traversal directives
~~~~~~~~~~~~~~~~~~~~~~~~
-:func:`grok.traversable` -- mark attributes or methods as traversable
-=====================================================================
+:func:`grok.traversable`
+========================
+Mark attributes or methods as traversable.
+
A class level directive used to mark attributes or methods as traversable. An
optional `name` argument can be used to give the attribute a different name in
the URL.
More information about the Checkins
mailing list