[Checkins]
SVN: Sandbox/ulif/grok-reference-with-rest/doc/reference/
The Grok reference in ReST format. See REAME.txt.
Uli Fouquet
uli at gnufix.de
Wed Aug 29 23:33:44 EDT 2007
Log message for revision 79370:
The Grok reference in ReST format. See REAME.txt.
Changed:
U Sandbox/ulif/grok-reference-with-rest/doc/reference/README.txt
A Sandbox/ulif/grok-reference-with-rest/doc/reference/components.rst
D Sandbox/ulif/grok-reference-with-rest/doc/reference/components.tex
A Sandbox/ulif/grok-reference-with-rest/doc/reference/conf.py
A Sandbox/ulif/grok-reference-with-rest/doc/reference/contents.rst
A Sandbox/ulif/grok-reference-with-rest/doc/reference/core.rst
D Sandbox/ulif/grok-reference-with-rest/doc/reference/core.tex
A Sandbox/ulif/grok-reference-with-rest/doc/reference/decorators.rst
D Sandbox/ulif/grok-reference-with-rest/doc/reference/decorators.tex
A Sandbox/ulif/grok-reference-with-rest/doc/reference/directives.rst
D Sandbox/ulif/grok-reference-with-rest/doc/reference/directives.tex
A Sandbox/ulif/grok-reference-with-rest/doc/reference/events.rst
D Sandbox/ulif/grok-reference-with-rest/doc/reference/events.tex
A Sandbox/ulif/grok-reference-with-rest/doc/reference/exceptions.rst
D Sandbox/ulif/grok-reference-with-rest/doc/reference/exceptions.tex
A Sandbox/ulif/grok-reference-with-rest/doc/reference/functions.rst
D Sandbox/ulif/grok-reference-with-rest/doc/reference/functions.tex
A Sandbox/ulif/grok-reference-with-rest/doc/reference/index.rst
A Sandbox/ulif/grok-reference-with-rest/doc/reference/model.rst
D Sandbox/ulif/grok-reference-with-rest/doc/reference/model.tex
A Sandbox/ulif/grok-reference-with-rest/doc/reference/ref-tools.diff
D Sandbox/ulif/grok-reference-with-rest/doc/reference/reference.tex
-=-
Modified: Sandbox/ulif/grok-reference-with-rest/doc/reference/README.txt
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/README.txt 2007-08-29 22:31:42 UTC (rev 79369)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/README.txt 2007-08-30 03:33:43 UTC (rev 79370)
@@ -2,42 +2,84 @@
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.
+The manual is written using ReStructured Text (ReST) with support for
+the Python documentation markup. The ReST sources can be compiled into
+HTML. To build the manual, you need some special tools described
+below.
+The current documents were converted from LaTeX to ReST using Georg
+Brandls converter.py tool, which is part of the current doctools
+trunk. You can find it here::
+
+ http://svn.python.org/projects/doctools/trunk/
+
+
+Hints for documentation writers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As the format was switched from LaTeX to ReST, you might want to read
+some hints about the changed notation of entities. Please read::
+
+ http://docs.python.org/dev/documenting/fromlatex.html
+
+to learn more about the differences. General information about the
+markup can be found here::
+
+ http://docs.python.org/dev/documenting/index.html
+
+
Build the HTML
+~~~~~~~~~~~~~~
+
+Prerequisites:
--------------
-Compiling the sources into HTML::
+The HTML is generated basically by the new sphinx package in
+docutils. This *requires*:
- $ mkhowto --html reference.tex
+ * Python >= v2.5
-The directory 'reference/' keeps all files required to display the manual after
-that call and can be put on a static webserver.
+ * docutils >= v0.4
-Build the PDF
--------------
+*Optional* you can install pygments for syntax highlithing.
-The file 'reference.pdf' will contain the PDF version of the manual after this
-call::
+Basically, it should be sufficient, to check out sphinx and other
+helper tools from the docutils subversion repository::
- $ mkhowto --pdf reference.tex
+ $ cd doc/
+ $ svn co svn co http://svn.python.org/projects/doctools/trunk/ ref-tools
-Installing prerequisites on Debian and Ubuntu systems
------------------------------------------------------
+Checking out in the ``reference`` directory itself will cause trouble,
+so do it in the ``doc`` or another directory, which will not be parsed for
+rst files.
-On recent Debian and Ubuntu systems, the following packages provide the
-required toolset for compiling the sources.
+The current docutils tool-chain is pretty focused on Python
+documentation, including the original Python directory structure and
+other things more specific for Python documentation. I believe, that
+this will change but currently you have to tweak the original sources
+a bit, to run with other documentation.
-The basic LaTeX infrastructure::
+To generate Grok reference (and not pure Python documentation), the
+tools can be patched with the patch provided in ``reference/``.
- $ sudo apt-get install tetex-base tetex-bin tetex-extra latex2html
+ $ patch -p0 ref-tools < reference/ref-tools.diff
-The python-dev package provides the mkhowto script::
+The patch applies some changes to leave the index page untouched and
+to display Grok as project name.
- $ sudo apt-get install python2.4-dev
-This script will be located in::
+Compiling the sources into HTML::
+---------------------------------
- /usr/lib/python2.4/doc/tools/mkhowto
+Create a target directory::
+
+ $ mkdir ref-build
+
+and compile the ReST sources:
+
+ $ python2.5 ref-tools/sphinx-build.py -b html reference/ ref-build
+
+
+The build process is subject to change. The format will stay.
+
+
Added: Sandbox/ulif/grok-reference-with-rest/doc/reference/components.rst
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/components.rst (rev 0)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/components.rst 2007-08-30 03:33:43 UTC (rev 79370)
@@ -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: Sandbox/ulif/grok-reference-with-rest/doc/reference/components.tex
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/components.tex 2007-08-29 22:31:42 UTC (rev 79369)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/components.tex 2007-08-30 03:33:43 UTC (rev 79370)
@@ -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}}
Added: Sandbox/ulif/grok-reference-with-rest/doc/reference/conf.py
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/conf.py (rev 0)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/conf.py 2007-08-30 03:33:43 UTC (rev 79370)
@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+#
+# Python documentation build configuration file
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+
+# The default replacements for |version| and |release|.
+# If 'auto', Sphinx looks for the Include/patchlevel.h file in the current Python
+# source tree and replaces the values accordingly.
+#
+# The short X.Y version.
+# version = '2.6'
+version = '0.10'
+# The full version, including alpha/beta/rc tags.
+# release = '2.6a0'
+release = '0.10dev'
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%B %d, %Y'
+
+# The base URL for download links.
+download_base_url = 'http://grok.zope.org/reference/'
+
+# List of files that shouldn't be included in the build.
+unused_files = [
+ 'whatsnew/2.0.rst',
+ 'whatsnew/2.1.rst',
+ 'whatsnew/2.2.rst',
+ 'whatsnew/2.3.rst',
+ 'whatsnew/2.4.rst',
+ 'whatsnew/2.5.rst',
+ 'maclib/scrap.rst',
+ 'library/xmllib.rst',
+ 'library/xml.etree.rst',
+]
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+last_updated_format = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+use_smartypants = True
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = True
+
Added: Sandbox/ulif/grok-reference-with-rest/doc/reference/contents.rst
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/contents.rst (rev 0)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/contents.rst 2007-08-30 03:33:43 UTC (rev 79370)
@@ -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
Added: Sandbox/ulif/grok-reference-with-rest/doc/reference/core.rst
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/core.rst (rev 0)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/core.rst 2007-08-30 03:33:43 UTC (rev 79370)
@@ -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: Sandbox/ulif/grok-reference-with-rest/doc/reference/core.tex
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/core.tex 2007-08-29 22:31:42 UTC (rev 79369)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/core.tex 2007-08-30 03:33:43 UTC (rev 79370)
@@ -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}
-
Added: Sandbox/ulif/grok-reference-with-rest/doc/reference/decorators.rst
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/decorators.rst (rev 0)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/decorators.rst 2007-08-30 03:33:43 UTC (rev 79370)
@@ -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: Sandbox/ulif/grok-reference-with-rest/doc/reference/decorators.tex
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/decorators.tex 2007-08-29 22:31:42 UTC (rev 79369)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/decorators.tex 2007-08-30 03:33:43 UTC (rev 79370)
@@ -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}
Added: Sandbox/ulif/grok-reference-with-rest/doc/reference/directives.rst
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/directives.rst (rev 0)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/directives.rst 2007-08-30 03:33:43 UTC (rev 79370)
@@ -0,0 +1,325 @@
+
+**********
+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`, :class:`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::
+
+ :class:`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`
+===================
+
+
+.. function:: grok.Fields(*arg)
+
+ foobar
+
+
+:func:`grok.implements`
+=======================
+
+
+.. function:: grok.implements(*arg)
+
+ foobar
+
+
+:func:`grok.context`
+====================
+
+
+.. function:: grok.context(*arg)
+
+ foobar
+
+
+:func:`grok.global_utility`
+===========================
+
+
+.. function:: grok.global_utility(*arg)
+
+ foobar
+
+
+:func:`grok.name`
+=================
+
+
+.. function:: grok.name(*arg)
+
+ foobar
+
+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.
+
+
+:func:`grok.local_utility`
+==========================
+
+
+.. function:: grok.local_utility(*arg)
+
+ foobar
+
+
+: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
+
Deleted: Sandbox/ulif/grok-reference-with-rest/doc/reference/directives.tex
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/directives.tex 2007-08-29 22:31:42 UTC (rev 79369)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/directives.tex 2007-08-30 03:33:43 UTC (rev 79370)
@@ -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}
Added: Sandbox/ulif/grok-reference-with-rest/doc/reference/events.rst
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/events.rst (rev 0)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/events.rst 2007-08-30 03:33:43 UTC (rev 79370)
@@ -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: Sandbox/ulif/grok-reference-with-rest/doc/reference/events.tex
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/events.tex 2007-08-29 22:31:42 UTC (rev 79369)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/events.tex 2007-08-30 03:33:43 UTC (rev 79370)
@@ -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}
Added: Sandbox/ulif/grok-reference-with-rest/doc/reference/exceptions.rst
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/exceptions.rst (rev 0)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/exceptions.rst 2007-08-30 03:33:43 UTC (rev 79370)
@@ -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: Sandbox/ulif/grok-reference-with-rest/doc/reference/exceptions.tex
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/exceptions.tex 2007-08-29 22:31:42 UTC (rev 79369)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/exceptions.tex 2007-08-30 03:33:43 UTC (rev 79370)
@@ -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}
Added: Sandbox/ulif/grok-reference-with-rest/doc/reference/functions.rst
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/functions.rst (rev 0)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/functions.rst 2007-08-30 03:33:43 UTC (rev 79370)
@@ -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: Sandbox/ulif/grok-reference-with-rest/doc/reference/functions.tex
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/functions.tex 2007-08-29 22:31:42 UTC (rev 79369)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/functions.tex 2007-08-30 03:33:43 UTC (rev 79370)
@@ -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}
Added: Sandbox/ulif/grok-reference-with-rest/doc/reference/index.rst
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/index.rst (rev 0)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/index.rst 2007-08-30 03:33:43 UTC (rev 79370)
@@ -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
Added: Sandbox/ulif/grok-reference-with-rest/doc/reference/model.rst
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/model.rst (rev 0)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/model.rst 2007-08-30 03:33:43 UTC (rev 79370)
@@ -0,0 +1,9 @@
+
+**********
+grok.Model
+**********
+
+
+Models
+======
+
Deleted: Sandbox/ulif/grok-reference-with-rest/doc/reference/model.tex
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/model.tex 2007-08-29 22:31:42 UTC (rev 79369)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/model.tex 2007-08-30 03:33:43 UTC (rev 79370)
@@ -1,3 +0,0 @@
-\chapter{grok.Model}
-
- \section{Models}
Added: Sandbox/ulif/grok-reference-with-rest/doc/reference/ref-tools.diff
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/ref-tools.diff (rev 0)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/ref-tools.diff 2007-08-30 03:33:43 UTC (rev 79370)
@@ -0,0 +1,87 @@
+Index: ref-tools/sphinx/templates/layout.html
+===================================================================
+--- ref-tools/sphinx/templates/layout.html (Revision 57692)
++++ ref-tools/sphinx/templates/layout.html (Arbeitskopie)
+@@ -1,4 +1,4 @@
+-{% if builder != 'htmlhelp' %}{% set titlesuffix = " — Python Documentation" %}{% endif -%}
++{% if builder != 'htmlhelp' %}{% set titlesuffix = " — Grok Reference" %}{% endif -%}
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+ "http://www.w3.org/TR/html4/loose.dtd">
+ <html>
+@@ -31,7 +31,7 @@
+ <link rel="index" title="Global index" href="{{ pathto('genindex.rst') }}">
+ <link rel="search" title="Search" href="{{ pathto('search.rst') }}">
+ <link rel="copyright" title="Copyright" href="{{ pathto('copyright.rst') }}">
+- <link rel="top" title="Python Documentation" href="{{ pathto('index.rst') }}">
++ <link rel="top" title="Grok Reference" href="{{ pathto('index.rst') }}">
+ {%- if parents %}
+ <link rel="up" title="{{ parents[-1].title|striptags }}" href="{{ parents[-1].link|e }}">
+ {%- endif %}
+@@ -60,7 +60,7 @@
+ <li class="right"><a href="{{ pathto('settings.rst') }}"
+ title="Customize your viewing settings">settings</a> |</li>
+ {%- endif %}
+- <li><a href="{{ pathto('index.rst') }}">Python v{{ release }} Documentation</a> »</li>
++ <li><a href="{{ pathto('index.rst') }}">Grok Reference for v{{ release }}</a> »</li>
+ {%- for parent in parents %}
+ <li><a href="{{ parent.link|e }}">{{ parent.title }}</a> »</li>
+ {%- endfor %}
+@@ -86,8 +86,8 @@
+ </div>
+ {{ relbar }}
+ <div class="footer">
+- © <a href="{{ pathto('copyright.rst') }}">Copyright</a>
+- 1990-2007, Python Software Foundation.
++ © Copyright
++ 2006-2007, The Zope Foundation.
+ {% if last_updated %}Last updated on {{ last_updated }}.{% endif %}
+ </div>
+ </body>
+Index: ref-tools/sphinx/refcounting.py
+===================================================================
+--- ref-tools/sphinx/refcounting.py (Revision 57692)
++++ ref-tools/sphinx/refcounting.py (Arbeitskopie)
+@@ -10,8 +10,8 @@
+ :license: Python license.
+ """
+ from __future__ import with_statement
++import os
+
+-
+ class RCEntry:
+ def __init__(self, name):
+ self.name = name
+@@ -24,6 +24,10 @@
+ @classmethod
+ def fromfile(cls, filename):
+ d = cls()
++ if not os.path.isfile(filename):
++ if not os.path.isdir(os.path.dirname(filename)):
++ os.makedirs(os.path.dirname(filename))
++ open(filename, 'w').close()
+ with open(filename, 'r') as fp:
+ for line in fp:
+ line = line.strip()
+Index: ref-tools/sphinx/builder.py
+===================================================================
+--- ref-tools/sphinx/builder.py (Revision 57692)
++++ ref-tools/sphinx/builder.py (Arbeitskopie)
+@@ -446,7 +446,7 @@
+ pathto = relpath_to(self, self.get_target_uri('index.rst')),
+ current_page_name = 'index',
+ )
+- self.handle_file('index.rst', indexcontext, 'index')
++ #self.handle_file('index.rst', indexcontext, 'index')
+
+ # the search page
+ searchcontext = dict(
+@@ -498,7 +498,8 @@
+ except (IOError, OSError):
+ pass
+ # delete all entries for files that will be rebuilt
+- self.indexer.prune(set(self.env.all_files) - set(filenames))
++ if filenames is not None:
++ self.indexer.prune(set(self.env.all_files) - set(filenames))
+
+ def index_file(self, filename, doctree, title):
+ # only index pages with title
Deleted: Sandbox/ulif/grok-reference-with-rest/doc/reference/reference.tex
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/reference.tex 2007-08-29 22:31:42 UTC (rev 79369)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/reference.tex 2007-08-30 03:33:43 UTC (rev 79370)
@@ -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