[Checkins] SVN: grok/branches/neanderthal-reference-documentation/
Create a branch for continuing the reference documentation in ReST.
Jan-Wijbrand Kolman
janwijbrand at gmail.com
Mon Oct 1 12:55:03 EDT 2007
Log message for revision 80447:
Create a branch for continuing the reference documentation in ReST.
Changed:
A grok/branches/neanderthal-reference-documentation/
D grok/branches/neanderthal-reference-documentation/doc/reference/README.txt
A grok/branches/neanderthal-reference-documentation/doc/reference/README.txt
A grok/branches/neanderthal-reference-documentation/doc/reference/components.rst
D grok/branches/neanderthal-reference-documentation/doc/reference/components.tex
A grok/branches/neanderthal-reference-documentation/doc/reference/contents.rst
A grok/branches/neanderthal-reference-documentation/doc/reference/core.rst
D grok/branches/neanderthal-reference-documentation/doc/reference/core.tex
A grok/branches/neanderthal-reference-documentation/doc/reference/decorators.rst
D grok/branches/neanderthal-reference-documentation/doc/reference/decorators.tex
A grok/branches/neanderthal-reference-documentation/doc/reference/directives.rst
D grok/branches/neanderthal-reference-documentation/doc/reference/directives.tex
A grok/branches/neanderthal-reference-documentation/doc/reference/events.rst
D grok/branches/neanderthal-reference-documentation/doc/reference/events.tex
A grok/branches/neanderthal-reference-documentation/doc/reference/exceptions.rst
D grok/branches/neanderthal-reference-documentation/doc/reference/exceptions.tex
A grok/branches/neanderthal-reference-documentation/doc/reference/functions.rst
D grok/branches/neanderthal-reference-documentation/doc/reference/functions.tex
A grok/branches/neanderthal-reference-documentation/doc/reference/index.rst
A grok/branches/neanderthal-reference-documentation/doc/reference/model.rst
D grok/branches/neanderthal-reference-documentation/doc/reference/model.tex
D grok/branches/neanderthal-reference-documentation/doc/reference/reference.tex
-=-
Copied: grok/branches/neanderthal-reference-documentation (from rev 80438, grok/trunk)
Deleted: grok/branches/neanderthal-reference-documentation/doc/reference/README.txt
===================================================================
--- grok/trunk/doc/reference/README.txt 2007-10-01 08:24:51 UTC (rev 80438)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/README.txt 2007-10-01 16:55:03 UTC (rev 80447)
@@ -1,43 +0,0 @@
-=========================
-The grok reference manual
-=========================
-
-The manual is written using LaTeX with support for the Python documentation
-markup. The tex sources can be compiled to HTML and PDF. To build the manual,
-you need the 'mkhowto' script from a recent Python source distribution.
-
-Build the HTML
---------------
-
-Compiling the sources into HTML::
-
- $ mkhowto --html reference.tex
-
-The directory 'reference/' keeps all files required to display the manual after
-that call and can be put on a static webserver.
-
-Build the PDF
--------------
-
-The file 'reference.pdf' will contain the PDF version of the manual after this
-call::
-
- $ mkhowto --pdf reference.tex
-
-Installing prerequisites on Debian and Ubuntu systems
------------------------------------------------------
-
-On recent Debian and Ubuntu systems, the following packages provide the
-required toolset for compiling the sources.
-
-The basic LaTeX infrastructure::
-
- $ sudo apt-get install tetex-base tetex-bin tetex-extra latex2html
-
-The python-dev package provides the mkhowto script::
-
- $ sudo apt-get install python2.4-dev
-
-This script will be located in::
-
- /usr/lib/python2.4/doc/tools/mkhowto
Copied: grok/branches/neanderthal-reference-documentation/doc/reference/README.txt (from rev 80444, grok/trunk/doc/reference/README.txt)
===================================================================
--- grok/branches/neanderthal-reference-documentation/doc/reference/README.txt (rev 0)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/README.txt 2007-10-01 16:55:03 UTC (rev 80447)
@@ -0,0 +1,6 @@
+=========================
+The grok reference manual
+=========================
+
+NOTE: The Grok reference manual is in the process of being migrated to a
+RestructuredText infrastructure.
Copied: grok/branches/neanderthal-reference-documentation/doc/reference/components.rst (from rev 80443, grok/trunk/doc/reference/components.rst)
===================================================================
--- grok/branches/neanderthal-reference-documentation/doc/reference/components.rst (rev 0)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/components.rst 2007-10-01 16:55:03 UTC (rev 80447)
@@ -0,0 +1,289 @@
+
+**********
+Components
+**********
+
+The :mod:`grok` module defines a set of components that provide basic Zope 3
+functionality in a convenient way.
+
+
+:class:`grok.Adapter`
+=====================
+
+Implementation, configuration, and registration of Zope 3 adapters.
+
+
+.. class:: grok.Adapter
+
+ Base class to define an adapter. Adapters are automatically registered when a
+ module is "grokked".
+
+
+ .. attribute:: grok.Adapter.context
+
+ The adapted object.
+
+ **Directives:**
+
+ :func:`grok.context(context_obj_or_interface)`
+ Maybe required. Identifies the type of objects or interface for the adaptation.
+
+ If Grok can determine a context for adaptation from the module, this directive
+ can be omitted. If the automatically determined context is not correct, or if no
+ context can be derived from the module the directive is required.
+
+ :func:`grok.implements(\*interfaces)`
+ Required. Identifies the interface(s) the adapter implements.
+
+ :func:`grok.name(name)`
+ Optional. Identifies the name used for the adapter registration. If ommitted, no
+ name will be used.
+
+ When a name is used for the adapter registration, the adapter can only be
+ retrieved by explicitely using its name.
+
+ :func:`grok.provides(name)`
+ Maybe required. If the adapter implements more than one interface,
+ :func:`grok.provides` is required to disambiguate for what interface the adapter
+ will be registered.
+
+**Example:** ::
+
+ import grok
+ from zope import interface
+
+ class Cave(grok.Model):
+ pass
+
+ class IHome(interface.Interface):
+ pass
+
+ class Home(grok.Adapter):
+ grok.implements(IHome)
+
+ home = IHome(cave)
+
+**Example 2:** ::
+
+ import grok
+ from zope import interface
+
+ class Cave(grok.Model):
+ pass
+
+ class IHome(interface.Interface):
+ pass
+
+ class Home(grok.Adapter):
+ grok.implements(IHome)
+ grok.name('home')
+
+ from zope.component import getAdapter
+ home = getAdapter(cave, IHome, name='home')
+
+
+:class:`grok.AddForm`
+=====================
+
+
+:class:`grok.Annotation`
+========================
+
+
+:class:`grok.Application`
+=========================
+
+
+grok.ClassGrokker
+=================
+
+
+:class:`grok.Container`
+=======================
+
+
+.. class:: grok.Container
+
+ Mixin base class to define a container object. The container implements the
+ zope.app.container.interfaces.IContainer interface using a BTree, providing
+ reasonable performance for large collections of objects.
+
+
+:class:`grok.DisplayForm`
+=========================
+
+
+:class:`grok.EditForm`
+======================
+
+
+:class:`grok.Form`
+==================
+
+
+:class:`grok.GlobalUtility`
+===========================
+
+
+.. class:: grok.GlobalUtility
+
+ Base class to define a globally registered utility. Global utilities are
+ automatically registered when a module is "grokked".
+
+ **Directives:**
+
+ :func:`grok.implements(\*interfaces)`
+ Required. Identifies the interfaces(s) the utility implements.
+
+ :func:`grok.name(name)`
+ Optional. Identifies the name used for the adapter registration. If ommitted, no
+ name will be used.
+
+ When a name is used for the global utility registration, the global utility can
+ only be retrieved by explicitely using its name.
+
+ :func:`grok.provides(name)`
+ Maybe required. If the global utility implements more than one interface,
+ :func:`grok.provides` is required to disambiguate for what interface the global
+ utility will be registered.
+
+
+:class:`grok.Indexes`
+=====================
+
+
+grok.InstanceGrokker
+====================
+
+
+:class:`grok.JSON`
+==================
+
+
+:class:`grok.LocalUtility`
+==========================
+
+
+.. class:: grok.LocalUtility
+
+ Base class to define a utility that will be registered local to a
+ :class:`grok.Site` or :class:`grok.Application` object by using the
+ :func:`grok.local_utility` directive.
+
+ **Directives:**
+
+ :func:`grok.implements(\*interfaces)`
+ Optional. Identifies the interfaces(s) the utility implements.
+
+ :func:`grok.name(name)`
+ Optional. Identifies the name used for the adapter registration. If ommitted, no
+ name will be used.
+
+ When a name is used for the local utility registration, the local utility can
+ only be retrieved by explicitely using its name.
+
+ :func:`grok.provides(name)`
+ Maybe required. If the local utility implements more than one interface or if
+ the implemented interface cannot be determined, :func:`grok.provides` is
+ required to disambiguate for what interface the local utility will be
+ registered.
+
+
+.. seealso::
+
+ Local utilities need to be registered in the context of :class:`grok.Site` or
+ :class:`grok.Application` using the :func:`grok.local_utility` directive.
+
+
+:class:`grok.Model`
+===================
+
+Base class to define an application "content" or model object. Model objects
+provide persistence and containment.
+
+
+grok.ModuleGrokker
+==================
+
+
+:class:`grok.MultiAdapter`
+==========================
+
+
+.. class:: grok.MultiAdapter
+
+ Base class to define a multi adapter. MultiAdapters are automatically registered
+ when a module is "grokked".
+
+ **Directives:**
+
+ :func:`grok.adapts(\*objects_or_interfaces)`
+ Required. Identifies the combination of types of objects or interfaces for the
+ adaptation.
+
+ :func:`grok.implements(\*interfaces)`
+ Required. Identifies the interfaces(s) the adapter implements.
+
+ :func:`grok.name(name)`
+ Optional. Identifies the name used for the adapter registration. If ommitted, no
+ name will be used.
+
+ When a name is used for the adapter registration, the adapter can only be
+ retrieved by explicitely using its name.
+
+ :func:`grok.provides(name)`
+ Maybe required. If the adapter implements more than one interface,
+ :func:`grok.provides` is required to disambiguate for what interface the adapter
+ will be registered.
+
+**Example:** ::
+
+ import grok
+ from zope import interface
+
+ class Fireplace(grok.Model):
+ pass
+
+ class Cave(grok.Model):
+ pass
+
+ class IHome(interface.Interface):
+ pass
+
+ class Home(grok.MultiAdapter):
+ grok.adapts(Cave, Fireplace)
+ grok.implements(IHome)
+
+ def __init__(self, cave, fireplace):
+ self.cave = cave
+ self.fireplace = fireplace
+
+ home = IHome(cave, fireplace)
+
+
+grok.PageTemplate
+=================
+
+
+grok.PageTemplateFile
+=====================
+
+
+:class:`grok.Site`
+==================
+
+Base class to define an site object. Site objects provide persistence and
+containment.
+
+
+:class:`grok.Traverser`
+=======================
+
+
+:class:`grok.View`
+==================
+
+
+:class:`grok.XMLRPC`
+====================
+
Deleted: grok/branches/neanderthal-reference-documentation/doc/reference/components.tex
===================================================================
--- grok/trunk/doc/reference/components.tex 2007-10-01 08:24:51 UTC (rev 80438)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/components.tex 2007-10-01 16:55:03 UTC (rev 80447)
@@ -1,238 +0,0 @@
-\chapter{Components}
-
-The \module{grok} module defines a set of components that provide basic Zope 3
-functionality in a convenient way.
-
-\section{\class{grok.Adapter}}
-
- Implementation, configuration, and registration of Zope 3 adapters.
-
- \begin{classdesc*}{grok.Adapter}
- Base class to define an adapter. Adapters are automatically registered when
- a module is "grokked".
-
- \begin{memberdesc}{context}
- The adapted object.
- \end{memberdesc}
-
- \begin{bf}Directives:\end{bf}
-
- \begin{itemize}
- \item[\function{grok.context(context_obj_or_interface)}] Maybe required.
- Identifies the type of objects or interface for the adaptation.
-
- If Grok can determine a context for adaptation from the module, this
- directive can be omitted. If the automatically determined context is not
- correct, or if no context can be derived from the module the directive is
- required.
-
- \item[\function{grok.implements(*interfaces)}] Required. Identifies the
- interface(s) the adapter implements.
-
- \item[\function{grok.name(name)}] Optional. Identifies the name used for
- the adapter registration. If ommitted, no name will be used.
-
- When a name is used for the adapter registration, the adapter can only be
- retrieved by explicitely using its name.
-
- \item[\function{grok.provides(name)}] Maybe required. If the adapter
- implements more than one interface, \function{grok.provides} is required to
- disambiguate for what interface the adapter will be registered.
- \end{itemize}
- \end{classdesc*}
-
- \begin{bf}Example:\end{bf}
-
- \begin{verbatim}
-import grok
-from zope import interface
-
-class Cave(grok.Model):
- pass
-
-class IHome(interface.Interface):
- pass
-
-class Home(grok.Adapter):
- grok.implements(IHome)
-
-home = IHome(cave)
- \end{verbatim}
-
- \begin{bf}Example 2:\end{bf}
-
- \begin{verbatim}
-import grok
-from zope import interface
-
-class Cave(grok.Model):
- pass
-
-class IHome(interface.Interface):
- pass
-
-class Home(grok.Adapter):
- grok.implements(IHome)
- grok.name('home')
-
-from zope.component import getAdapter
-home = getAdapter(cave, IHome, name='home')
- \end{verbatim}
-
-\section{\class{grok.AddForm}}
-
-\section{\class{grok.Annotation}}
-
-\section{\class{grok.Application}}
-
-\section{grok.ClassGrokker}
-
-\section{\class{grok.Container}}
-
- \begin{classdesc*}{grok.Container}
- Mixin base class to define a container object. The container implements the
- zope.app.container.interfaces.IContainer interface using a BTree, providing
- reasonable performance for large collections of objects.
- \end{classdesc*}
-
-\section{\class{grok.DisplayForm}}
-
-\section{\class{grok.EditForm}}
-
-\section{\class{grok.Form}}
-
-\section{\class{grok.GlobalUtility}}
-
- \begin{classdesc*}{grok.GlobalUtility}
- Base class to define a globally registered utility. Global utilities are
- automatically registered when a module is "grokked".
-
- \begin{bf}Directives:\end{bf}
-
- \begin{itemize}
- \item[\function{grok.implements(*interfaces)}] Required. Identifies the
- interfaces(s) the utility implements.
-
- \item[\function{grok.name(name)}] Optional. Identifies the name used for
- the adapter registration. If ommitted, no name will be used.
-
- When a name is used for the global utility registration, the global utility
- can only be retrieved by explicitely using its name.
-
- \item[\function{grok.provides(name)}] Maybe required. If the global utility
- implements more than one interface, \function{grok.provides} is required to
- disambiguate for what interface the global utility will be registered.
- \end{itemize}
- \end{classdesc*}
-
-\section{\class{grok.Indexes}}
-
-\section{grok.InstanceGrokker}
-
-\section{\class{grok.JSON}}
-
-\section{\class{grok.LocalUtility}}
-
- \begin{classdesc*}{grok.LocalUtility}
- Base class to define a utility that will be registered local to a
- \class{grok.Site} or \class{grok.Application} object by using the
- \function{grok.local_utility} directive.
-
- \begin{bf}Directives:\end{bf}
-
- \begin{itemize}
- \item[\function{grok.implements(*interfaces)}] Optional. Identifies the
- interfaces(s) the utility implements.
-
- \item[\function{grok.name(name)}] Optional. Identifies the name used for
- the adapter registration. If ommitted, no name will be used.
-
- When a name is used for the local utility registration, the local utility
- can only be retrieved by explicitely using its name.
-
- \item[\function{grok.provides(name)}] Maybe required. If the local utility
- implements more than one interface or if the implemented interface cannot
- be determined, \function{grok.provides} is required to disambiguate for
- what interface the local utility will be registered.
- \end{itemize}
- \end{classdesc*}
-
- \begin{seealso}
- Local utilities need to be registered in the context of \class{grok.Site} or
- \class{grok.Application} using the \function{grok.local_utility} directive.
- \end{seealso}
-
-\section{\class{grok.Model}}
-
- Base class to define an application "content" or model object. Model objects
- provide persistence and containment.
-
-\section{grok.ModuleGrokker}
-
-\section{\class{grok.MultiAdapter}}
-
- \begin{classdesc*}{grok.MultiAdapter}
- Base class to define a multi adapter. MultiAdapters are automatically
- registered when a module is "grokked".
-
- \begin{bf}Directives:\end{bf}
-
- \begin{itemize}
- \item[\function{grok.adapts(*objects_or_interfaces)}] Required. Identifies
- the combination of types of objects or interfaces for the adaptation.
-
- \item[\function{grok.implements(*interfaces)}] Required. Identifies the
- interfaces(s) the adapter implements.
-
- \item[\function{grok.name(name)}] Optional. Identifies the name used for
- the adapter registration. If ommitted, no name will be used.
-
- When a name is used for the adapter registration, the adapter can only
- be retrieved by explicitely using its name.
-
- \item[\function{grok.provides(name)}] Maybe required. If the adapter
- implements more than one interface, \function{grok.provides} is required to
- disambiguate for what interface the adapter will be registered.
- \end{itemize}
- \end{classdesc*}
-
- \begin{bf}Example:\end{bf}
-
- \begin{verbatim}
-import grok
-from zope import interface
-
-class Fireplace(grok.Model):
- pass
-
-class Cave(grok.Model):
- pass
-
-class IHome(interface.Interface):
- pass
-
-class Home(grok.MultiAdapter):
- grok.adapts(Cave, Fireplace)
- grok.implements(IHome)
-
- def __init__(self, cave, fireplace):
- self.cave = cave
- self.fireplace = fireplace
-
-home = IHome(cave, fireplace)
- \end{verbatim}
-
-\section{grok.PageTemplate}
-
-\section{grok.PageTemplateFile}
-
-\section{\class{grok.Site}}
-
- Base class to define an site object. Site objects provide persistence and
- containment.
-
-\section{\class{grok.Traverser}}
-
-\section{\class{grok.View}}
-
-\section{\class{grok.XMLRPC}}
Copied: grok/branches/neanderthal-reference-documentation/doc/reference/contents.rst (from rev 80443, grok/trunk/doc/reference/contents.rst)
===================================================================
--- grok/branches/neanderthal-reference-documentation/doc/reference/contents.rst (rev 0)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/contents.rst 2007-10-01 16:55:03 UTC (rev 80447)
@@ -0,0 +1,18 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+ Grok Documentation contents
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+.. toctree::
+
+ core.rst
+ components.rst
+ directives.rst
+ decorators.rst
+ functions.rst
+ events.rst
+ exceptions.rst
+
+bugs.rst
+about.rst
+license.rst
+copyright.rst
Copied: grok/branches/neanderthal-reference-documentation/doc/reference/core.rst (from rev 80443, grok/trunk/doc/reference/core.rst)
===================================================================
--- grok/branches/neanderthal-reference-documentation/doc/reference/core.rst (rev 0)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/core.rst 2007-10-01 16:55:03 UTC (rev 80447)
@@ -0,0 +1,45 @@
+
+****
+Core
+****
+
+The :mod:`grok` module defines a few functions to interact with grok itself.
+
+
+:func:`grok.grok` -- Grok a package or module
+=============================================
+
+
+.. function:: grok(dotted_name)
+
+ Grokking a package or module activates the contained components (like models,
+ views, adapters, templates, etc.) and registers them with Zope 3's component
+ architecture.
+
+ The `dotted_name` must specify either a Python module or package that is
+ available from the current PYTHONPATH.
+
+ Grokking a module:
+
+#. Scan the module for known components: models, adapters, utilities, views,
+ traversers, templates and subscribers.
+
+#. Check whether a directory with file system templates exists
+ (:file:`<modulename>_templates`). If it exists, load the file system templates
+ into the template registry for this module.
+
+#. Determine the module context.
+
+#. Register all components with the Zope 3 component architecture.
+
+#. Initialize schemata for registered models
+
+ Grokking a package:
+
+#. Grok the package as a module.
+
+#. Check for a static resource directory (:file:`static`) and register it if it
+ exists.
+
+#. Recursively grok all sub-modules and sub-packages.
+
Deleted: grok/branches/neanderthal-reference-documentation/doc/reference/core.tex
===================================================================
--- grok/trunk/doc/reference/core.tex 2007-10-01 08:24:51 UTC (rev 80438)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/core.tex 2007-10-01 16:55:03 UTC (rev 80447)
@@ -1,50 +0,0 @@
-\chapter{Core}
-
-The \module{grok} module defines a few functions to interact with grok itself.
-
-
-\section{\function{grok.grok} -- Grok a package or module}
-
- \begin{funcdesc}{grok}{dotted_name}
-
- Grokking a package or module activates the contained components (like
- models, views, adapters, templates, etc.) and registers them with Zope 3's
- component architecture.
-
- The \var{dotted_name} must specify either a Python module or package
- that is available from the current PYTHONPATH.
-
- Grokking a module:
-
- \begin{enumerate}
-
- \item Scan the module for known components: models, adapters,
- utilities, views, traversers, templates and subscribers.
-
- \item Check whether a directory with file system templates
- exists (\file{<modulename>_templates}). If it exists,
- load the file system templates into the template
- registry for this module.
-
- \item Determine the module context.
-
- \item Register all components with the Zope 3 component architecture.
-
- \item Initialize schemata for registered models
-
- \end{enumerate}
-
- Grokking a package:
-
- \begin{enumerate}
- \item Grok the package as a module.
-
- \item Check for a static resource directory (\file{static})
- and register it if it exists.
-
- \item Recursively grok all sub-modules and sub-packages.
-
- \end{enumerate}
-
- \end{funcdesc}
-
Copied: grok/branches/neanderthal-reference-documentation/doc/reference/decorators.rst (from rev 80443, grok/trunk/doc/reference/decorators.rst)
===================================================================
--- grok/branches/neanderthal-reference-documentation/doc/reference/decorators.rst (rev 0)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/decorators.rst 2007-10-01 16:55:03 UTC (rev 80447)
@@ -0,0 +1,28 @@
+
+**********
+Decorators
+**********
+
+grok uses a few decorators to register functions or methods for specific
+functionality.
+
+
+:func:`grok.subscribe` -- Register a function as a subscriber for an event
+==========================================================================
+
+
+.. function:: subscribe(*classes_or_interfaces)
+
+ Declare that the decorated function subscribes to an event or a combination of
+ objects and events and register it.
+
+ Applicable on module-level for functions. Requires at least one class or
+ interface as argument.
+
+ (Similar to Zope 3's :func:`subscriber` decorator, but automatically performs
+ the registration of the component.)
+
+
+grok.action
+===========
+
Deleted: grok/branches/neanderthal-reference-documentation/doc/reference/decorators.tex
===================================================================
--- grok/trunk/doc/reference/decorators.tex 2007-10-01 08:24:51 UTC (rev 80438)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/decorators.tex 2007-10-01 16:55:03 UTC (rev 80447)
@@ -1,21 +0,0 @@
-\chapter{Decorators}
-
-grok uses a few decorators to register functions or methods for specific
-functionality.
-
- \section{\function{grok.subscribe} -- Register a function as a subscriber
- for an event}
-
- \begin{funcdesc}{subscribe}{*classes_or_interfaces}
-
- Declare that the decorated function subscribes to an event or a
- combination of objects and events and register it.
-
- Applicable on module-level for functions. Requires at least one class
- or interface as argument.
-
- (Similar to Zope 3's \function{subscriber} decorator, but automatically
- performs the registration of the component.)
- \end{funcdesc}
-
- \section{grok.action}
Copied: grok/branches/neanderthal-reference-documentation/doc/reference/directives.rst (from rev 80443, grok/trunk/doc/reference/directives.rst)
===================================================================
--- grok/branches/neanderthal-reference-documentation/doc/reference/directives.rst (rev 0)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/directives.rst 2007-10-01 16:55:03 UTC (rev 80447)
@@ -0,0 +1,566 @@
+
+**********
+Directives
+**********
+
+The :mod:`grok` module defines a set of directives that allow you to configure
+and register your components. Most directives assume a default, based on the
+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.
+
+
+:func:`grok.AutoFields` -- Deduce schema fields automatically
+=============================================================
+
+
+.. function:: grok.AutoFields(class_or_interface)
+
+ A class level directive, which can be used inside :class:`Form`
+ classes to automatically deduce the form fields from the schema of
+ the context `class_or_interface`.
+
+ Different to most other directives, :func:`grok.AutoFields` is used
+ more like a function and less like a pure declaration.
+
+ The following example makes use of the :func:`grok.AutoFields`
+ directive, in that one field is omitted from the form before
+ rendering:
+
+**Example:** ::
+
+ import grok
+ from zope import interface, schema
+
+ 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 Edit(grok.EditForm):
+ grok.context(Mammoth)
+
+ form_fields = grok.AutoFields(Mammoth).omit('size')
+
+In this example the ``size`` attribute will not show up in the
+resulting edit view.
+
+
+.. seealso::
+
+ :class:`grok.EditForm`, :func:`grok.Fields`
+
+
+: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`.
+
+ 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.
+
+ **Example:** ::
+
+ 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 Mammoth(grok.Model):
+ interface.implements(IMammoth)
+
+ class MammothSize(object):
+ grok.implements(ISized)
+ grok.adapts(IMammoth)
+
+ def __init__(self, context):
+ self.context = context
+
+ def sizeForSorting(self):
+ return ('byte', 1000)
+
+ def sizeForDisplay(self):
+ return ('1000 bytes')
+
+ 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'
+
+
+ .. seealso::
+
+ :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.
+
+ 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).
+
+ **Example:** ::
+
+ import grok
+
+ class ModelBase(grok.Model):
+ pass
+
+ class ViewBase(grok.View):
+ def render(self):
+ return "hello world"
+
+ class AnotherView(grok.View):
+ grok.baseclass()
+
+ def render(self):
+ return "hello world"
+
+ 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`.
+
+
+:func:`grok.define_permission` -- define a permission
+=====================================================
+
+
+.. function:: grok.define_permission(name)
+
+ A module-level directive to define a permission with name
+ `name`. Usually permission names are prefixed by a component- or
+ application name and a dot to keep them unique.
+
+ Because in Grok by default everything is accessible by everybody,
+ it is important to define permissions, which restrict access to
+ certain principals or roles.
+
+ **Example:** ::
+
+ import grok
+ grok.define_permission('cave.enter')
+
+
+ .. seealso::
+
+ :func:`grok.require`, :class:`grok.Permission`, :class:`grok.Role`
+
+ .. versionchanged:: 0.11
+ replaced by :class:`grok.Permission`.
+
+
+:func:`grok.Fields` -- declare schema fields of a form
+======================================================
+
+.. function:: grok.Fields(**schemas)
+
+ A class level directive, which can be used inside :class:`grok.Form`
+ classes.
+
+ A :class:`grok.Fields` can receive keyword parameters with schema
+ fields. These should be available in the definition order.
+
+ **Example:** ::
+
+ import grok
+ from zope import schema
+
+ class Mammoth(grok.Model):
+ pass
+
+ class Edit(grok.EditForm):
+ fields = grok.Fields(
+ b = schema.TextLine(title=u"Beta"),
+ a = schema.TextLine(title=u"Alpha"),
+
+ Given the above code, when the :class:`Edit` form is rendered, the
+ :class:`Textlines` `b` and `a` will appear as input fields in that
+ order. This is due to the fact, that by default the `fields`
+ variable is taken into account, when rendering forms.
+
+ .. seealso::
+
+ :func:`grok.AutoFields`, :class:`grok.Form`
+
+
+:func:`grok.implements` -- indicate, that a class implements an interface
+=========================================================================
+
+
+.. 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.
+
+ :func:`grok.implements` is currently an alias for
+ :func:`zope.interface.implements`.
+
+ **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
+
+
+:func:`grok.context` -- Declare the context for views, adapters, etc.
+=====================================================================
+
+
+.. 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:**
+
+ 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
+
+ class Mammoth(grok.Model):
+ pass
+
+ class Cave(grok.Model):
+ pass
+
+ class Index(grok.View):
+ grok.context(Mammoth)
+
+
+
+ .. seealso::
+
+ :class:`grok.View`, :class:`grok.Adapter`, :class:`grok.MultiAdapter`
+
+
+
+
+: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.
+
+ `factory` - the factory that creates the utility.
+
+ `provides` - the interface the utility should be looked up with.
+
+ `name` - the name of the utility.
+
+ 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.
+
+ Another way to register global utilities with Grok is to subclass
+ from :class:`grok.GlobalUtility`.
+
+
+ **Example:**
+
+ Given the following module code: ::
+
+ import grok
+ from zope import interface
+
+ class IFireplace(interface.Interface):
+ pass
+
+ class Fireplace(object):
+ grok.implements(IFireplace)
+
+ grok.global_utility(Fireplace)
+ grok.global_utility(Fireplace, name='hot')
+
+ Then the following works: ::
+
+ >>> 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
+
+ .. seealso::
+
+ :class:`grok.GlobalUtility`, :func:`grok.provides`,
+ :func:`grok.implements`
+
+
+: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.
+
+ **Example:** ::
+
+ import grok
+
+ class Mammoth(grok.Model):
+ pass
+
+ class Index(grok.View):
+ grok.name('index')
+
+
+ .. seealso::
+
+ :class:`grok.Adapter`, :class:`grok.Annotation`,
+ :class:`grok.GlobalUtility`, :class:`grok.Indexes`,
+ :class:`grok.MultiAdapter`, :class:`grok.Role`,
+ :class:`grok.View`
+
+
+
+
+: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.
+
+ `factory` -- the factory that creates the utility.
+
+ `provides` -- the interface the utility should be looked up with.
+
+ `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.
+
+ `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.
+
+ 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`.
+
+ 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.
+
+ An alternative way to define a local utility is to subclass from
+ :class:`grok.LocalUtility`.
+
+ **Example:**
+
+ The following code registers a local unnamed utility `fireplace` in
+ instances of :class:`Cave` ::
+
+ import grok
+ from zope import interface
+
+ class IFireplace(interface.Interface):
+ pass
+
+ class Fireplace(grok.LocalUtility):
+ grok.implements(IFireplace)
+
+ class Cave(grok.Container, grok.Site):
+ grok.local_utility(Fireplace, public=True,
+ name_in_container='fireplace')
+
+
+ .. seealso::
+
+ :func:`grok.global_utility`, :class:`grok.LocalUtility`
+
+
+:func:`grok.provides`
+=====================
+
+
+.. function:: grok.provides(*arg)
+
+ foobar
+
+
+:func:`grok.resourcedir --- XXX Not implemented yet`
+====================================================
+
+
+.. function:: grok.resourcedir(*arg)
+
+ foobar
+
+ 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)
+
+ 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:**
+
+ 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.
+
+
+Linking to resources from templates
+-----------------------------------
+
+grok provides a convenient way to calculate the URLs to static
+resource using the keyword :keyword:`static` in page templates::
+
+<link rel="stylesheet" tal:attributes="href static/example.css" type="text/css">
+
+The keyword :keyword:`static` will be replaced by the reference to
+the resource directory for the package in which the template was
+registered.
+
+
+:func:`grok.require`
+====================
+
+
+.. function:: grok.require(*arg)
+
+ foobar
+
+
+:func:`grok.site`
+=================
+
+
+.. function:: grok.site(*arg)
+
+ foobar
+
+
+:func:`grok.template`
+=====================
+
+
+.. function:: grok.template(*arg)
+
+ foobar
+
+
+:func:`grok.templatedir`
+========================
+
+
+.. function:: grok.templatedir(*arg)
+
+ foobar
+
+
+:func:`grok.title`
+========================
+
+
+.. function:: grok.title(*arg)
+
+ foobar
+
Deleted: grok/branches/neanderthal-reference-documentation/doc/reference/directives.tex
===================================================================
--- grok/trunk/doc/reference/directives.tex 2007-10-01 08:24:51 UTC (rev 80438)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/directives.tex 2007-10-01 16:55:03 UTC (rev 80447)
@@ -1,302 +0,0 @@
-\chapter{Directives}
-
-The \module{grok} module defines a set of directives that allow you to
-configure and register your components. Most directives assume a
-default, based on the 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.
-
-
- \section{\function{grok.AutoFields} -- deduce schema fields automatically}
-
- \begin{funcdesc}{grok.AutoFields}{class_or_interface}
- A class level directive, which can be used inside
- \class{Form} classes to automatically deduce the form fields
- from the schema of the context \var{class_or_interface}.
-
- Different to most other directives,
- \function{grok.AutoFields} is used more like a function and
- less like a pure declaration.
-
- The following example makes use of the
- \function{grok.AutoFields} directive, in that one field is
- omitted from the form before rendering:
-
- \strong{Example:}
-
- \begin{verbatim}
-import grok
-from zope import interface, schema
-
-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 Edit(grok.EditForm):
- grok.context(Mammoth)
-
- form_fields = grok.AutoFields(Mammoth).omit('size')
- \end{verbatim}
-
- In this example the \code{size} attribute will not show up
- in the resulting edit view.
-
- \begin{seealso}
- \class{grok.EditForm}, \class{grok.Fields}
- \end{seealso}
-
- \end{funcdesc}
-
- \section{\function{grok.adapts} -- declare that a class adapts
- certain objects}
-
- \begin{funcdesc}{grok.adapts}{*classes_or_interfaces}
- A class-level directive to declare that a class adapts
- objects of the classes or interfaces given in
- \var{*classes_or_interfaces}.
-
- This directive accepts several arguments.
-
- It works much like the \module{zope.component}s
- \function{adapts()}, but you do not have to make a ZCML
- entry to register the adapter.
-
- \strong{Example:}
-
- \begin{verbatim}
-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 Mammoth(grok.Model):
- interface.implements(IMammoth)
-
-class MammothSize(object):
- grok.implements(ISized)
- grok.adapts(IMammoth)
-
- def __init__(self, context):
- self.context = context
-
- def sizeForSorting(self):
- return ('byte', 1000)
-
- def sizeForDisplay(self):
- return ('1000 bytes')
- \end{verbatim}
-
- Having \class{MammothSize} available, you can register it as
- an adapter, without a single line of ZCML:
-
- \begin{verbatim}
->>> manfred = Mammoth()
->>> from zope.component import provideAdapter
->>> provideAdapter(MammothSize)
->>> from zope.size.interfaces import ISized
->>> size = ISized(manfred)
->>> size.sizeForDisplay()
-'1000 bytes'
- \end{verbatim}
-
- \begin{seealso}
- \class{grok.implements}
- \end{seealso}
-
- \end{funcdesc}
-
- \section{\function{grok.baseclass} -- declare a class as base}
-
- \begin{funcdesc}{grok.baseclass}{}
- 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 \code{'Base'}.
-
- The baseclass mark is not inherited by subclasses, so those
- subclasses will be grokked (except they are explicitly
- declared as baseclasses as well).
-
- \strong{Example:}
-
- \begin{verbatim}
-import grok
-
-class ModelBase(grok.Model):
- pass
-
-class ViewBase(grok.View):
- def render(self):
- return "hello world"
-
-class AnotherView(grok.View):
- grok.baseclass()
-
- def render(self):
- return "hello world"
-
-class WorkingView(grok.View):
- pass
- \end{verbatim}
-
- Using this example, only the \class{WorkingView} will serve
- as a view, while calling the \class{ViewBase} or
- \class{AnotherView} will lead to a
- \exception{ComponentLookupError}.
-
-
- \end{funcdesc}
-
- \section{\function{grok.define_permission} -- define a permission}
-
- \begin{funcdesc}{grok.define_permission}{name}
-
- A module-level directive to define a permission with name
- \var{name}. Usually permission names are prefixed by a
- component- or application name and a dot to keep them
- unique.
-
- Because in Grok by default everything is accessible by
- everybody, it is important to define permissions, which
- restrict access to certain principals or roles.
-
- \strong{Example:}
-
- \begin{verbatim}
-import grok
-grok.define_permission('cave.enter')
- \end{verbatim}
-
- \begin{seealso}
- \function{grok.require()}, \class{grok.Permission},
- \class{grok.Role}
- \end{seealso}
-
- \versionchanged[replaced by \class{grok.Permission}]{0.11}
-
- \end{funcdesc}
-
-
-
- \section{\function{grok.Fields}}
-
- \begin{funcdesc}{grok.Fields}{*arg}
- foobar
- \end{funcdesc}
-
- \section{\function{grok.implements}}
-
- \begin{funcdesc}{grok.implements}{*arg}
- foobar
- \end{funcdesc}
-
- \section{\function{grok.context}}
-
- \begin{funcdesc}{grok.context}{*arg}
- foobar
- \end{funcdesc}
-
- \section{\function{grok.global_utility}}
-
- \begin{funcdesc}{grok.global_utility}{*arg}
- foobar
- \end{funcdesc}
-
- \section{\function{grok.name}}
-
- \begin{funcdesc}{grok.name}{*arg}
- foobar
- \end{funcdesc}
-
- Used to associate a component with a name. Typically this directive is
- optional. The default behaviour when no name is given depends on the
- component.
-
- \section{\function{grok.local_utility}}
-
- \begin{funcdesc}{grok.local_utility}{*arg}
- foobar
- \end{funcdesc}
-
- \section{\function{grok.provides}}
-
- \begin{funcdesc}{grok.provides}{*arg}
- foobar
- \end{funcdesc}
-
- \section{\function{grok.resourcedir --- XXX Not implemented yet}}
-
- \begin{funcdesc}{grok.resourcedir}{*arg}
- foobar
- \end{funcdesc}
-
- 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)
-
- 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>}.
-
- \begin{bf}Example:\end{bf} The package \module{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}.
-
- \begin{notice}
- 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.
- \end{notice}
-
- \subsection{Linking to resources from templates}
-
- grok provides a convenient way to calculate the URLs to static
- resource using the keyword \keyword{static} in page templates:
-
- \begin{verbatim}
-<link rel="stylesheet" tal:attributes="href static/example.css" type="text/css">
- \end{verbatim}
-
- The keyword \keyword{static} will be replaced by the reference to
- the resource directory for the package in which the template was
- registered.
-
- \section{\function{grok.require}}
-
- \begin{funcdesc}{grok.require}{*arg}
- foobar
- \end{funcdesc}
-
- \section{\function{grok.site}}
-
- \begin{funcdesc}{grok.site}{*arg}
- foobar
- \end{funcdesc}
-
- \section{\function{grok.template}}
-
- \begin{funcdesc}{grok.template}{*arg}
- foobar
- \end{funcdesc}
-
- \section{\function{grok.templatedir}}
-
- \begin{funcdesc}{grok.templatedir}{*arg}
- foobar
- \end{funcdesc}
Copied: grok/branches/neanderthal-reference-documentation/doc/reference/events.rst (from rev 80443, grok/trunk/doc/reference/events.rst)
===================================================================
--- grok/branches/neanderthal-reference-documentation/doc/reference/events.rst (rev 0)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/events.rst 2007-10-01 16:55:03 UTC (rev 80447)
@@ -0,0 +1,65 @@
+
+******
+Events
+******
+
+grok provides convenient access to a set of often-used events from Zope 3. Those
+events include object and containment events. All events are available as
+interface and implemented class.
+
+
+grok.IContainerModifiedEvent
+============================
+
+
+grok.IObjectAddedEvent
+======================
+
+
+grok.IObjectCopiedEvent
+=======================
+
+
+grok.IObjectCreatedEvent
+========================
+
+
+grok.IObjectModifiedEvent
+=========================
+
+
+grok.IObjectMovedEvent
+======================
+
+
+grok.IObjectRemovedEvent
+========================
+
+
+grok.ContainerModifiedEvent
+===========================
+
+
+grok.ObjectAddedEvent
+=====================
+
+
+grok.ObjectCopiedEvent
+======================
+
+
+grok.ObjectCreatedEvent
+=======================
+
+
+grok.ObjectModifiedEvent
+========================
+
+
+grok.ObjectMovedEvent
+=====================
+
+
+grok.ObjectRemovedEvent
+=======================
+
Deleted: grok/branches/neanderthal-reference-documentation/doc/reference/events.tex
===================================================================
--- grok/trunk/doc/reference/events.tex 2007-10-01 08:24:51 UTC (rev 80438)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/events.tex 2007-10-01 16:55:03 UTC (rev 80447)
@@ -1,33 +0,0 @@
-\chapter{Events}
-
-grok provides convenient access to a set of often-used events from Zope 3.
-Those events include object and containment events. All events are available as
-interface and implemented class.
-
- \section{grok.IContainerModifiedEvent}
-
- \section{grok.IObjectAddedEvent}
-
- \section{grok.IObjectCopiedEvent}
-
- \section{grok.IObjectCreatedEvent}
-
- \section{grok.IObjectModifiedEvent}
-
- \section{grok.IObjectMovedEvent}
-
- \section{grok.IObjectRemovedEvent}
-
- \section{grok.ContainerModifiedEvent}
-
- \section{grok.ObjectAddedEvent}
-
- \section{grok.ObjectCopiedEvent}
-
- \section{grok.ObjectCreatedEvent}
-
- \section{grok.ObjectModifiedEvent}
-
- \section{grok.ObjectMovedEvent}
-
- \section{grok.ObjectRemovedEvent}
Copied: grok/branches/neanderthal-reference-documentation/doc/reference/exceptions.rst (from rev 80443, grok/trunk/doc/reference/exceptions.rst)
===================================================================
--- grok/branches/neanderthal-reference-documentation/doc/reference/exceptions.rst (rev 0)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/exceptions.rst 2007-10-01 16:55:03 UTC (rev 80447)
@@ -0,0 +1,59 @@
+
+**********
+Exceptions
+**********
+
+grok tries to inform you about errors early and with as much guidance as
+possible. grok can detect some errors already while importing a module, which
+will lead to the :class:`GrokImportError`. Other errors require more context
+and can only be detected while executing the :func:`grok` function.
+
+
+:class:`grok.GrokImportError` -- errors while importing a module
+================================================================
+
+This exception is raised if a grok-specific problem was found while importing a
+module of your application. :class:`GrokImportError` means there was a problem
+in how you are using a part of grok. The error message tries to be as
+informative as possible tell you why something went wrong and how you can fix
+it.
+
+:class:`GrokImportError` is a subclass of Python's :class:`ImportError`.
+
+Examples of situations in which a GrokImportError occurs:
+
+* Using a directive in the wrong context (e.g. grok.templatedir on class-level
+ instead of module-level.)
+
+* Using a decorator with wrong arguments (e.g. grok.subscribe without any
+ argument)
+
+* ...
+
+
+:class:`grok.GrokError` -- errors while grokking a module
+=========================================================
+
+This exception is raised if an error occurs while grokking a module.
+
+Typically a :class:`GrokError` will be raised if one of your modules uses a
+feature of grok that requires some sort of unambigous context to establish a
+reasonable default.
+
+For example, the :class:`grok.View` requires exactly one model to be defined
+locally in the module to assume a default module to be associated with. Having
+no model defined, or more than one model, will lead to an error because the
+context is either underspecified or ambigous.
+
+The error message of a :class:`GrokError` will include the reason for the error,
+the place in your code that triggered the error, and a hint, to help you fix the
+error.
+
+
+.. class:: GrokError(Exception)
+
+
+ .. attribute:: GrokError.component
+
+ The component that was grokked and triggered the error.
+
Deleted: grok/branches/neanderthal-reference-documentation/doc/reference/exceptions.tex
===================================================================
--- grok/trunk/doc/reference/exceptions.tex 2007-10-01 08:24:51 UTC (rev 80438)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/exceptions.tex 2007-10-01 16:55:03 UTC (rev 80447)
@@ -1,49 +0,0 @@
-\chapter{Exceptions}
-
-grok tries to inform you about errors early and with as much guidance as
-possible. grok can detect some errors already while importing a module, which
-will lead to the \class{GrokImportError}. Other errors require more context
-and can only be detected while executing the \function{grok} function.
-
- \section{\class{grok.GrokImportError} -- errors while importing a module}
-
- This exception is raised if a grok-specific problem was found while
- importing a module of your application. \class{GrokImportError} means there
- was a problem in how you are using a part of grok. The error message tries
- to be as informative as possible tell you why something went wrong and how
- you can fix it.
-
- \class{GrokImportError} is a subclass of Python's \class{ImportError}.
-
- Examples of situations in which a GrokImportError occurs:
-
- \begin{itemize}
- \item Using a directive in the wrong context (e.g. grok.templatedir on
- class-level instead of module-level.)
- \item Using a decorator with wrong arguments (e.g. grok.subscribe
- without any argument)
- \item \ldots
- \end{itemize}
-
- \section{\class{grok.GrokError} -- errors while grokking a module}
-
- This exception is raised if an error occurs while grokking a module.
-
- Typically a \class{GrokError} will be raised if one of your modules uses a
- feature of grok that requires some sort of unambigous context to establish
- a reasonable default.
-
- For example, the \class{grok.View} requires exactly one model to be defined
- locally in the module to assume a default module to be associated with.
- Having no model defined, or more than one model, will lead to an error
- because the context is either underspecified or ambigous.
-
- The error message of a \class{GrokError} will include the reason for the
- error, the place in your code that triggered the error, and a hint, to help
- you fix the error.
-
- \begin{classdesc}{GrokError}{Exception}
- \begin{memberdesc}{component}
- The component that was grokked and triggered the error.
- \end{memberdesc}
- \end{classdesc}
Copied: grok/branches/neanderthal-reference-documentation/doc/reference/functions.rst (from rev 80443, grok/trunk/doc/reference/functions.rst)
===================================================================
--- grok/branches/neanderthal-reference-documentation/doc/reference/functions.rst (rev 0)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/functions.rst 2007-10-01 16:55:03 UTC (rev 80447)
@@ -0,0 +1,81 @@
+
+*********
+Functions
+*********
+
+The :mod:`grok` module provides a number of convenience functions to aid in
+common tasks.
+
+
+:func:`grok.getSite`
+====================
+
+
+.. function:: grok.getSite()
+
+ Get the current site object.
+
+
+ .. seealso::
+
+ Site objects are instances of :class:`grok.Site` and/or
+ :class:`grok.Application`.
+
+
+ .. seealso::
+
+ `Web Component Development With Zope 3, second edition <http://worldcookery.com/WhereToBuy>`_
+ By Philiip von Weitershaussen; Chapter 18 describes the use of Site objects.
+
+
+:func:`grok.notify`
+===================
+
+
+.. function:: grok.notify(event)
+
+ Send `event` to event subscribers.
+
+ Example::
+
+ import grok
+
+ class Mammoth(object):
+ def __init__(self, name):
+ self.name = name
+
+ manfred = Mammoth('manfred')
+
+ grok.notify(grok.ObjectCreatedEvent(manfred))
+
+
+ .. seealso::
+
+ Grok events provide a selection of common event types.
+
+
+ .. seealso::
+
+ `Web Component Development With Zope 3, second edition <http://worldcookery.com/WhereToBuy>`_
+ By Philiip von Weitershaussen; Chapter 16 describes the Zope 3 event system.
+
+
+:func:`grok.url`
+================
+
+
+.. function:: grok.url(request, object, [, name])
+
+ Construct a URL for the given `request` and `object`.
+
+ `name` may be a string that gets appended to the object URL. Commonly used to
+ construct an URL to a particular view on the object.
+
+ This function returns the constructed URL as a string.
+
+
+ .. seealso::
+
+ View classes derived from :class:`grok.View` have a similar :meth:`url` method
+ for constructing URLs.
+
Deleted: grok/branches/neanderthal-reference-documentation/doc/reference/functions.tex
===================================================================
--- grok/trunk/doc/reference/functions.tex 2007-10-01 08:24:51 UTC (rev 80438)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/functions.tex 2007-10-01 16:55:03 UTC (rev 80447)
@@ -1,72 +0,0 @@
-\chapter{Functions}
-
-The \module{grok} module provides a number of convenience functions to aid in
-common tasks.
-
- \section{\function{grok.getSite}}
-
- \begin{funcdesc}{grok.getSite}{}
- Get the current site object.
-
- \begin{seealso}
- Site objects are instances of \class{grok.Site} and/or
- \class{grok.Application}.
- \end{seealso}
-
- \begin{seealso}
- \seetitle
- [http://worldcookery.com/WhereToBuy]
- {Web Component Development With Zope 3, second edition}
- {By Philiip von Weitershaussen; Chapter 18 describes the use of Site
- objects.}
- \end{seealso}
-
- \end{funcdesc}
-
- \section{\function{grok.notify}}
-
- \begin{funcdesc}{grok.notify}{event}
- Send \var{event} to event subscribers.
-
- Example:
-\begin{verbatim}
-import grok
-
-class Mammoth(object):
- def __init__(self, name):
- self.name = name
-
-manfred = Mammoth('manfred')
-
-grok.notify(grok.ObjectCreatedEvent(manfred))
-\end{verbatim}
-
- \begin{seealso}
- Grok events provide a selection of common event types.
- \end{seealso}
-
- \begin{seealso}
- \seetitle
- [http://worldcookery.com/WhereToBuy]
- {Web Component Development With Zope 3, second edition}
- {By Philiip von Weitershaussen; Chapter 16 describes the Zope 3 event
- system.}
- \end{seealso}
-
- \end{funcdesc}
-
- \section{\function{grok.url}}
-
- \begin{funcdesc}{grok.url}{request, object, \optional{, name}}
- Construct a URL for the given \var{request} and \var{object}.
-
- \var{name} may be a string that gets appended to the object URL. Commonly
- used to construct an URL to a particular view on the object.
-
- This function returns the constructed URL as a string.
-
- \begin{seealso}
- View classes derived from \class{grok.View} have a similar \method{url}
- method for constructing URLs.
- \end{seealso}
- \end{funcdesc}
Copied: grok/branches/neanderthal-reference-documentation/doc/reference/index.rst (from rev 80443, grok/trunk/doc/reference/index.rst)
===================================================================
--- grok/branches/neanderthal-reference-documentation/doc/reference/index.rst (rev 0)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/index.rst 2007-10-01 16:55:03 UTC (rev 80447)
@@ -0,0 +1,36 @@
+.. _reference-index:
+
+#################################
+ Grok reference
+#################################
+
+:Release: |version|
+:Date: |today|
+
+ Grok means to understand so thoroughly that the observer becomes a part
+ of the observed -- merge, blend, intermarry, lose identity in group
+ experience. It means almost everything that we mean by religion,
+ philosophy, and science -- it means as little to us (because we are from
+ Earth) as color means to a blind man. -- `Robert A. Heinlein, Stranger in
+ a Strange Land`
+
+
+This is the grok reference documentation. It is organized by the Python
+artefacts that implement the concepts.
+
+Grok makes Zope 3 concepts more accessible for application developers. This
+reference is not intended as introductory material for those concepts. Please
+refer to the original Zope 3 documentation and the grok tutorial for
+introductory material.
+
+
+.. toctree::
+ :maxdepth: 2
+
+ core.rst
+ components.rst
+ directives.rst
+ decorators.rst
+ functions.rst
+ events.rst
+ exceptions.rst
Copied: grok/branches/neanderthal-reference-documentation/doc/reference/model.rst (from rev 80443, grok/trunk/doc/reference/model.rst)
===================================================================
--- grok/branches/neanderthal-reference-documentation/doc/reference/model.rst (rev 0)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/model.rst 2007-10-01 16:55:03 UTC (rev 80447)
@@ -0,0 +1,9 @@
+
+**********
+grok.Model
+**********
+
+
+Models
+======
+
Deleted: grok/branches/neanderthal-reference-documentation/doc/reference/model.tex
===================================================================
--- grok/trunk/doc/reference/model.tex 2007-10-01 08:24:51 UTC (rev 80438)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/model.tex 2007-10-01 16:55:03 UTC (rev 80447)
@@ -1,3 +0,0 @@
-\chapter{grok.Model}
-
- \section{Models}
Deleted: grok/branches/neanderthal-reference-documentation/doc/reference/reference.tex
===================================================================
--- grok/trunk/doc/reference/reference.tex 2007-10-01 08:24:51 UTC (rev 80438)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/reference.tex 2007-10-01 16:55:03 UTC (rev 80447)
@@ -1,71 +0,0 @@
-% Complete documentation on the extended LaTeX markup used for Python
-% documentation is available in ``Documenting Python'', which is part
-% of the standard documentation for Python. It may be found online
-% at:
-%
-% http://www.python.org/doc/current/doc/doc.html
-
-\documentclass{manual}
-\RequirePackage[latin9]{inputenc}
-\usepackage{graphicx}
-
-\title{grok reference}
-
-% Please at least include a long-lived email address;
-% the rest is at your discretion.
-\authoraddress{
- The grok team\\
- Email: $<$grok-dev at zope.org$>$
-}
-
-\date{\today} % update before release!
- % Use an explicit date so that reformatting
- % doesn't cause a new date to be used. Setting
- % the date to \today can be used during draft
- % stages to make it easier to handle versions.
-
-\release{unreleased} % release version; this is used to define the
- % \version macro
-
-\makeindex % tell \index to actually write the .idx file
-
-\begin{document}
-
-\maketitle
-
- \begin{quote}
- ``Grok means to understand so thoroughly that the observer becomes a part
- of the observed --- merge, blend, intermarry, lose identity in group
- experience. It means almost everything that we mean by religion,
- philosophy, and science --- it means as little to us (because we are from
- Earth) as color means to a blind man.'' -- Robert A. Heinlein, Stranger in
- a Strange Land
- \end{quote}
-
-\begin{abstract}
-This is the grok reference documentation. It is organized by the Python
-artefacts that implement the concepts.
-
-Grok makes Zope 3 concepts more accessible for application developers. This
-reference is not intended as introductory material for those concepts. Please
-refer to the original Zope 3 documentation and the grok tutorial for
-introductory material.
-\end{abstract}
-
-\tableofcontents
-
-\include{core}
-
-\include{components}
-
-\include{directives}
-
-\include{decorators}
-
-\include{functions}
-
-\include{events}
-
-\include{exceptions}
-
-\end{document}
More information about the Checkins
mailing list