[Checkins] SVN: grok/branches/neanderthal-reference-documentation/doc/reference/directives.rst added missing directives; defined a new format for documenting conventions for directives

Luciano Ramalho luciano at ramalho.org
Tue Oct 2 10:53:28 EDT 2007


Log message for revision 80498:
  added missing directives; defined a new format for documenting conventions for directives
  

Changed:
  U   grok/branches/neanderthal-reference-documentation/doc/reference/directives.rst

-=-
Modified: grok/branches/neanderthal-reference-documentation/doc/reference/directives.rst
===================================================================
--- grok/branches/neanderthal-reference-documentation/doc/reference/directives.rst	2007-10-02 14:52:40 UTC (rev 80497)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/directives.rst	2007-10-02 14:53:27 UTC (rev 80498)
@@ -26,70 +26,70 @@
 
 .. 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.
+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.
+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:**
+**Example:**
 
-   Here the :func:`grok.context` directive indicates, that
-   :class:`Mammoth` instances will be the context of :class:`Index`
-   views (and not instances of :class:`Cave`) ::
+Here the :func:`grok.context` directive indicates, that
+:class:`Mammoth` instances will be the context of :class:`Index`
+views (and not instances of :class:`Cave`) ::
 
-      import grok
+   import grok
 
-      class Mammoth(grok.Model):
-          pass
+   class Mammoth(grok.Model):
+       pass
 
-      class Cave(grok.Model):
-          pass
+   class Cave(grok.Model):
+       pass
 
-      class Index(grok.View):
-          grok.context(Mammoth)
+   class Index(grok.View):
+       grok.context(Mammoth)
 
-   .. seealso::
+.. seealso::
 
-      :class:`grok.View`, :class:`grok.Adapter`, :class:`grok.MultiAdapter`
+   :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 name
-   `name`. Typically this directive is optional. The default behaviour when no
-   name is given depends on the component. The same applies to the semantics of
-   this directive: for what exactly a name is set when using this directive,
-   depends on the component.
+A class level directive used to associate a component with a single name
+`name`. Typically this directive is optional. The default behaviour when no
+name is given depends on the component. The same applies to the semantics of
+this directive: for what exactly a name is set when using this directive,
+depends on the component.
 
-   **Example:** ::
+**Example:** ::
 
-      import grok
+   import grok
 
-      class Mammoth(grok.Model):
-         pass
+   class Mammoth(grok.Model):
+      pass
 
-      # a common use case is to have a URL for a view named differently than
-      # the name of the view class itself.
-      class SomeView(grok.View):
-         grok.name('index')
+   # a common use case is to have a URL for a view named differently than
+   # the name of the view class itself.
+   class SomeView(grok.View):
+      grok.name('index')
 
 
-   .. seealso::
+.. seealso::
 
-      :class:`grok.Adapter`, :class:`grok.Annotation`,
-      :class:`grok.GlobalUtility`, :class:`grok.Indexes`,
-      :class:`grok.MultiAdapter`, :class:`grok.Role`,
-      :class:`grok.View`
+   :class:`grok.Adapter`, :class:`grok.Annotation`,
+   :class:`grok.GlobalUtility`, :class:`grok.Indexes`,
+   :class:`grok.MultiAdapter`, :class:`grok.Role`,
+   :class:`grok.View`
 
 :func:`grok.title`
 ========================
@@ -103,136 +103,136 @@
 
 .. function:: grok.implements(*interfaces)
 
-   A class level directive to declare one or more `interfaces`, as implementers
-   of the surrounding class. This directive allows several parameters.
+A class level directive to declare one or more `interfaces`, as implementers
+of the surrounding class. This directive allows several parameters.
 
-   :func:`grok.implements` is currently an alias for
-   :func:`zope.interface.implements`.
+:func:`grok.implements` is currently an alias for
+:func:`zope.interface.implements`.
 
-   **Example:** ::
+**Example:** ::
 
-      >>> import grok
-      >>> from zope import interface
-      >>> class IPaintable(interface.Interface):
-      ...   pass
-      ...
-      >>> class Cave(object):
-      ...   pass
-      ...
-      >>> cave = Cave()
-      >>> IPaintable.providedBy(cave)
-      False
-      >>> class PaintableCave(object):
-      ...   grok.implements(IPaintable)
-      ...
-      >>> cave = PaintableCave()
-      >>> IPaintable.providedBy(cave)
-      True
+   >>> import grok
+   >>> from zope import interface
+   >>> class IPaintable(interface.Interface):
+   ...   pass
+   ...
+   >>> class Cave(object):
+   ...   pass
+   ...
+   >>> cave = Cave()
+   >>> IPaintable.providedBy(cave)
+   False
+   >>> class PaintableCave(object):
+   ...   grok.implements(IPaintable)
+   ...
+   >>> cave = PaintableCave()
+   >>> IPaintable.providedBy(cave)
+   True
 
 :func:`grok.provides`
 =====================
 
 .. function:: grok.provides(interface)
 
-   If the component implements more than one interface, :func:`grok.provides`
-   is required to disambiguate for what interface the component will be
-   registered.
+If the component implements more than one interface, :func:`grok.provides`
+is required to disambiguate for what interface the component will be
+registered.
 
-   .. seealso::
+.. seealso::
 
-      :func:`grok.implements`
+   :func:`grok.implements`
 
 :func:`grok.adapts` -- Declare that a class adapts certain objects
 ==================================================================
 
 .. 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`.
+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.
+This directive accepts several arguments.
 
-   It works much like the :mod:`zope.component`\ s :func:`adapts()`, but you do
-   not have to make a ZCML entry to register the adapter.
+It works much like the :mod:`zope.component`\ s :func:`adapts()`, but you do
+not have to make a ZCML entry to register the adapter.
 
-   **Example:** ::
+**Example:** ::
 
-      import grok
-      from zope import interface, schema
-      from zope.size.interfaces import ISized
+   import grok
+   from zope import interface, schema
+   from zope.size.interfaces import ISized
 
-      class IMammoth(interface.Interface):
-          name = schema.TextLine(title=u"Name")
-          size = schema.TextLine(title=u"Size", default=u"Quite normal")
+   class IMammoth(interface.Interface):
+       name = schema.TextLine(title=u"Name")
+       size = schema.TextLine(title=u"Size", default=u"Quite normal")
 
-      class Mammoth(grok.Model):
-          interface.implements(IMammoth)
+   class Mammoth(grok.Model):
+       interface.implements(IMammoth)
 
-      class MammothSize(object):
-          grok.implements(ISized)
-          grok.adapts(IMammoth)
+   class MammothSize(object):
+       grok.implements(ISized)
+       grok.adapts(IMammoth)
 
-          def __init__(self, context):
-              self.context = context
+       def __init__(self, context):
+           self.context = context
 
-          def sizeForSorting(self):
-              return ('byte', 1000)
+       def sizeForSorting(self):
+           return ('byte', 1000)
 
-          def sizeForDisplay(self):
-              return ('1000 bytes')
+       def sizeForDisplay(self):
+           return ('1000 bytes')
 
-   Having :class:`MammothSize` available, you can register it as an adapter,
-   without a single line of ZCML::
+Having :class:`MammothSize` available, you can register it as an adapter,
+without a single line of ZCML::
 
-      >>> manfred = Mammoth()
-      >>> from zope.component import provideAdapter
-      >>> provideAdapter(MammothSize)
-      >>> from zope.size.interfaces import ISized
-      >>> size = ISized(manfred)
-      >>> size.sizeForDisplay()
-      '1000 bytes'
+   >>> manfred = Mammoth()
+   >>> from zope.component import provideAdapter
+   >>> provideAdapter(MammothSize)
+   >>> from zope.size.interfaces import ISized
+   >>> size = ISized(manfred)
+   >>> size.sizeForDisplay()
+   '1000 bytes'
 
-   .. seealso::
+.. seealso::
 
-      :func:`grok.implements`
+   :func:`grok.implements`
 
 :func:`grok.baseclass` -- declare a class as base
 =================================================
 
 .. function:: grok.baseclass()
 
-   A class-level directive without argument to mark something as a base class.
-   Base classes are are not grokked.
+A class-level directive without argument to mark something as a base class.
+Base classes are are not grokked.
 
-   Another way to indicate that something is a base class, is by postfixing the
-   classname with ``'Base'``.
+Another way to indicate that something is a base class, is by postfixing the
+classname with ``'Base'``.
 
-   The baseclass mark is not inherited by subclasses, so those subclasses will
-   be grokked (except they are explicitly declared as baseclasses as well).
+The baseclass mark is not inherited by subclasses, so those subclasses will
+be grokked (except they are explicitly declared as baseclasses as well).
 
-   **Example:** ::
+**Example:** ::
 
-      import grok
+   import grok
 
-      class ModelBase(grok.Model):
-          pass
+   class ModelBase(grok.Model):
+       pass
 
-      class ViewBase(grok.View):
-          def render(self):
-              return "hello world"
+   class ViewBase(grok.View):
+       def render(self):
+           return "hello world"
 
-      class AnotherView(grok.View):
-          grok.baseclass()
+   class AnotherView(grok.View):
+       grok.baseclass()
 
-          def render(self):
-              return "hello world"
+       def render(self):
+           return "hello world"
 
-      class WorkingView(grok.View):
-          pass
+   class WorkingView(grok.View):
+       pass
 
-   Using this example, only the :class:`WorkingView` will serve as a view,
-   while calling the :class:`ViewBase` or :class:`AnotherView` will lead to a
-   :exc:`ComponentLookupError`.
+Using this example, only the :class:`WorkingView` will serve as a view,
+while calling the :class:`ViewBase` or :class:`AnotherView` will lead to a
+:exc:`ComponentLookupError`.
 
 Utility directives
 ~~~~~~~~~~~~~~~~~~
@@ -242,125 +242,125 @@
 
 .. function:: grok.global_utility(factory[, provides=None[, name=u'']])
 
-   A module level directive to register a global utility.
+A module level directive to register a global utility.
 
-   `factory` - the factory that creates the utility.
+`factory` - the factory that creates the utility.
 
-   `provides` - the interface the utility should be looked up with.
+`provides` - the interface the utility should be looked up with.
 
-   `name` - the name of the utility.
+`name` - the name of the utility.
 
-   The latter two parameters are optional.
+The latter two parameters are optional.
 
-   To register the utility correctly, Grok must be able to identify an
-   interface provided by the utility. If none is given, Grok checks whether
-   (exactly) one interface is implemented by the factory to be registered (see
-   example below). If more than one interface is implemented by a class, use
-   :func:`grok.provides` to specify which one to use. If no interface is
-   implemented by the instances delivered by the factory, use
-   :func:`grok.implements` to specify one.
+To register the utility correctly, Grok must be able to identify an
+interface provided by the utility. If none is given, Grok checks whether
+(exactly) one interface is implemented by the factory to be registered (see
+example below). If more than one interface is implemented by a class, use
+:func:`grok.provides` to specify which one to use. If no interface is
+implemented by the instances delivered by the factory, use
+:func:`grok.implements` to specify one.
 
-   Another way to register global utilities with Grok is to subclass from
-   :class:`grok.GlobalUtility`.
+Another way to register global utilities with Grok is to subclass from
+:class:`grok.GlobalUtility`.
 
-   **Example:**
+**Example:**
 
-      Given the following module code: ::
+   Given the following module code: ::
 
-         import grok
-         from zope import interface
+      import grok
+      from zope import interface
 
-         class IFireplace(interface.Interface):
-             pass
+      class IFireplace(interface.Interface):
+          pass
 
-         class Fireplace(object):
-             grok.implements(IFireplace)
+      class Fireplace(object):
+          grok.implements(IFireplace)
 
-         grok.global_utility(Fireplace)
-         grok.global_utility(Fireplace, name='hot')
+      grok.global_utility(Fireplace)
+      grok.global_utility(Fireplace, name='hot')
 
-      Then the following works: ::
+   Then the following works: ::
 
-         >>> from zope import component
-         >>> fireplace = component.getUtility(IFireplace)
-         >>> IFireplace.providedBy(fireplace)
-         True
-         >>> isinstance(fireplace, Fireplace)
-         True
+      >>> from zope import component
+      >>> fireplace = component.getUtility(IFireplace)
+      >>> IFireplace.providedBy(fireplace)
+      True
+      >>> isinstance(fireplace, Fireplace)
+      True
 
-         >>> fireplace = component.getUtility(IFireplace, name='hot')
-         >>> IFireplace.providedBy(fireplace)
-         True
-         >>> isinstance(fireplace, Fireplace)
-         True
+      >>> fireplace = component.getUtility(IFireplace, name='hot')
+      >>> IFireplace.providedBy(fireplace)
+      True
+      >>> isinstance(fireplace, Fireplace)
+      True
 
-   .. seealso::
+.. seealso::
 
-      :class:`grok.GlobalUtility`, :func:`grok.provides`,
-      :func:`grok.implements`
+   :class:`grok.GlobalUtility`, :func:`grok.provides`,
+   :func:`grok.implements`
 
 :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.
+A class level directive to register a local utility.
 
-   `factory` -- the factory that creates the utility.
+`factory` -- the factory that creates the utility.
 
-   `provides` -- the interface the utility should be looked up with.
+`provides` -- the interface the utility should be looked up with.
 
-   `name` -- the name of the utility.
+`name` -- the name of the utility.
 
-   `setup` -- a callable that receives the utility as its single
-      argument, it is called after the utility has been created and
-      stored.
+`setup` -- a callable that receives the utility as its single
+   argument, it is called after the utility has been created and
+   stored.
 
-   `public` -- if `False`, the utility will be stored below
-      `++etc++site`.  If `True`, the utility will be stored directly
-      in the site.  The site should in this case be a container.
+`public` -- if `False`, the utility will be stored below
+   `++etc++site`.  If `True`, the utility will be stored directly
+   in the site.  The site should in this case be a container.
 
-   `name_in_container` -- the name to use for storing the utility.
+`name_in_container` -- the name to use for storing the utility.
 
-   All but the first parameter are optional.
+All but the first parameter are optional.
 
-   To register a local utility correctly, Grok must know about the interface,
-   the utility should be looked up with. If none is given, Grok looks up any
-   interfaces implemented by instances delivered by `factory` and if exactly
-   one can be found, it is taken. See :func:`grok.global_utility`.
+To register a local utility correctly, Grok must know about the interface,
+the utility should be looked up with. If none is given, Grok looks up any
+interfaces implemented by instances delivered by `factory` and if exactly
+one can be found, it is taken. See :func:`grok.global_utility`.
 
-   Every single combination of interfaces and names can only be registered once
-   per module.
+Every single combination of interfaces and names can only be registered once
+per module.
 
-   It is not possible to declare a local utility as public, if the site is not
-   a container. Grok will remind you of this. To store a utility in a
-   container, a `name_in_container` is needed. If none is given, Grok will make
-   up one automatically.
+It is not possible to declare a local utility as public, if the site is not
+a container. Grok will remind you of this. To store a utility in a
+container, a `name_in_container` is needed. If none is given, Grok will make
+up one automatically.
 
-   An alternative way to define a local utility is to subclass from
-   :class:`grok.LocalUtility`.
+An alternative way to define a local utility is to subclass from
+:class:`grok.LocalUtility`.
 
-   **Example:**
+**Example:**
 
-      The following code registers a local unnamed utility `fireplace` in
-      instances of :class:`Cave` ::
+   The following code registers a local unnamed utility `fireplace` in
+   instances of :class:`Cave` ::
 
-         import grok
-         from zope import interface
+      import grok
+      from zope import interface
 
-         class IFireplace(interface.Interface):
-             pass
+      class IFireplace(interface.Interface):
+          pass
 
-         class Fireplace(grok.LocalUtility):
-             grok.implements(IFireplace)
+      class Fireplace(grok.LocalUtility):
+          grok.implements(IFireplace)
 
-         class Cave(grok.Container, grok.Site):
-             grok.local_utility(Fireplace, public=True,
-                                name_in_container='fireplace')
+      class Cave(grok.Container, grok.Site):
+          grok.local_utility(Fireplace, public=True,
+                             name_in_container='fireplace')
 
-   .. seealso::
+.. seealso::
 
-      :func:`grok.global_utility`, :class:`grok.LocalUtility`
+   :func:`grok.global_utility`, :class:`grok.LocalUtility`
 
 :func:`grok.resourcedir --- XXX Not implemented yet`
 ====================================================
@@ -369,28 +369,28 @@
 
    foobar
 
-   Resource directories are used to embed static resources like HTML-,
-   JavaScript-, CSS- and other files in your application.
+Resource directories are used to embed static resources like HTML-,
+JavaScript-, CSS- and other files in your application.
 
-   XXX insert directive description here (first: define the name, second:
-   describe the default behaviour if the directive isn't given)
+XXX insert directive description here (first: define the name, second:
+describe the default behaviour if the directive isn't given)
 
-   A resource directory is created when a package contains a directory with the
-   name :file:`static`. All files from this directory become accessible from a
-   browser under the URL
-   :file:`http://<servername>/++resource++<packagename>/<filename>`.
+A resource directory is created when a package contains a directory with the
+name :file:`static`. All files from this directory become accessible from a
+browser under the URL
+:file:`http://<servername>/++resource++<packagename>/<filename>`.
 
-   **Example:**
+**Example:**
 
-   The package :mod:`a.b.c` is grokked and contains a directory :file:`static`
-   which contains the file :file:`example.css`. The stylesheet will be
-   available via :file:`http://<servername>/++resource++a.b.c/example.css`.
+The package :mod:`a.b.c` is grokked and contains a directory :file:`static`
+which contains the file :file:`example.css`. The stylesheet will be
+available via :file:`http://<servername>/++resource++a.b.c/example.css`.
 
 .. note::
 
-   A package can never have both a :file:`static` directory and a Python module
-   with the name :file:`static.py` at the same time. grok will remind you of
-   this conflict when grokking a package by displaying an error message.
+A package can never have both a :file:`static` directory and a Python module
+with the name :file:`static.py` at the same time. grok will remind you of
+this conflict when grokking a package by displaying an error message.
 
 Linking to resources from templates
 -----------------------------------
@@ -409,27 +409,60 @@
 :func:`grok.require`
 ====================
 
-.. function:: grok.require(*arg)
+.. function:: grok.require(permission)
 
-   foobar
+A class level directive used to protect a View by requiring a certain permission. 
 
+`permission` -- the name of the permission that is required
+
+** Example **::
+
+	class ViewPainting(grok.Permission):
+	    grok.name('grok.ViewPainting')
+	
+
+.. seealso::
+
+  :class:`grok.Permission` component, :func:`@grok.require` decorator
+
+
 Template directives
 ~~~~~~~~~~~~~~~~~~~
 
 :func:`grok.template`
 =====================
 
-.. function:: grok.template(*arg)
+.. function:: grok.template(template)
 
-   foobar
+A class level directive used to specify the template to be rendered for the View when no render method is defined.
 
+`template` -- name of the template file
+
+** Convention **
+
+When not specified, Grok will look for a template file with the same name as the view class itself, lowercased, in the templates directory for this module.
+
+.. seealso::
+
+   :func:`grok.templatedir`
+
 :func:`grok.templatedir`
 ========================
 
-.. function:: grok.templatedir(*arg)
+A module level directive used to specify the directory where Grok should look for template files.
 
-   foobar
+.. function:: grok.templatedir(directory)
 
+`directory` -- the name of the directory inside the same package as the module
+
+** Convention **
+
+When not specified, Grok will look template files in a diretory named `<module>_templates` where `<module>` is the name of the current module.
+
+.. seealso::
+
+   :func:`grok.template`
+
 Uncategorized directives
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -438,4 +471,13 @@
 
 .. function:: grok.site(*arg)
 
-   foobar
+A class level directive used in `grok.Indexes` sub-classes to define in which local component registry the indexes should be located.
+
+** Example **
+::
+
+	class MammothIndexes(grok.Indexes):
+	    grok.site(Herd)
+	    grok.context(IMammoth)
+
+	    name = index.Field()



More information about the Checkins mailing list