[Checkins] SVN: grok/trunk/ Merge changes from ulif-docs2sphinx back into trunk.
Uli Fouquet
uli at gnufix.de
Thu Dec 30 07:02:25 EST 2010
Log message for revision 119220:
Merge changes from ulif-docs2sphinx back into trunk.
Changed:
U grok/trunk/CHANGES.txt
U grok/trunk/buildout.cfg
U grok/trunk/doc/README.rst
U grok/trunk/doc/conf.py
U grok/trunk/doc/contents.rst
U grok/trunk/doc/index.rst
U grok/trunk/doc/reference/components.rst
U grok/trunk/doc/reference/functions.rst
U grok/trunk/doc/reference/testing.rst
U grok/trunk/doc/upgrade.txt
U grok/trunk/setup.py
U grok/trunk/src/grok/components.py
U grok/trunk/src/grok/index.py
U grok/trunk/src/grok/testing.py
-=-
Modified: grok/trunk/CHANGES.txt
===================================================================
--- grok/trunk/CHANGES.txt 2010-12-30 11:29:05 UTC (rev 119219)
+++ grok/trunk/CHANGES.txt 2010-12-30 12:02:25 UTC (rev 119220)
@@ -4,6 +4,11 @@
1.4 (unreleased)
================
+- To build the docs we now use `collective.recipe.sphinxbuilder`
+ instead of our own, early hack (get rid of `grokdocs`
+ subpackage). Buildout now generates ``grokdocs2html`` and
+ ``grokdocs2pdf`` which should do what you think they do.
+
- The `IApplication` interface, and getApplication moved to
``grokcore.site``.
Modified: grok/trunk/buildout.cfg
===================================================================
--- grok/trunk/buildout.cfg 2010-12-30 11:29:05 UTC (rev 119219)
+++ grok/trunk/buildout.cfg 2010-12-30 12:02:25 UTC (rev 119220)
@@ -2,6 +2,7 @@
extends = http://svn.zope.org/repos/main/groktoolkit/trunk/grok.cfg
parts =
docs
+ pdfdocs
interpreter
grokwiki
mkdirs
@@ -10,7 +11,6 @@
zope_conf site_zcml deploy_ini debug_ini
develop =
.
- grokdocs
grokwiki
versions = versions
extensions = buildout.dumppickedversions
@@ -30,9 +30,24 @@
grok =
[docs]
-recipe = z3c.recipe.scripts
-eggs = grokdocs
+recipe = collective.recipe.sphinxbuilder
+eggs = grok [docs]
+build = ${buildout:directory}/build
+source = ${buildout:directory}/doc
+outputs = html
+script-name = grokdocs2html
+extra-paths = ${buildout:directory}/src
+[pdfdocs]
+recipe = collective.recipe.sphinxbuilder
+eggs = grok [docs]
+build = ${buildout:directory}/build
+source = ${buildout:directory}/doc
+outputs = pdf
+script-name = grokdocs2pdf
+extra-paths = ${buildout:directory}/src
+
+
[interpreter]
recipe = z3c.recipe.scripts
eggs = grokwiki
Modified: grok/trunk/doc/README.rst
===================================================================
--- grok/trunk/doc/README.rst 2010-12-30 11:29:05 UTC (rev 119219)
+++ grok/trunk/doc/README.rst 2010-12-30 12:02:25 UTC (rev 119220)
@@ -3,13 +3,11 @@
*********************
These documents are generated from `reStructuredText
-<http://docutils.sf.net/rst.html>`_ sources by *Sphinx*, an excellent
-document processor specifically written for the Python documentation
-by Georg Brandl and contributors.
+<http://docutils.sf.net/rst.html>`_ sources by `Sphinx
+<http://sphinx.pocoo.org>`_, an excellent document processor
+specifically written for the Python documentation by Georg Brandl and
+contributors.
-In the online version of these documents, you can submit comments and suggest
-changes directly on the documentation pages.
-
Development of this documentation and its toolchain takes place on the
grok-dev at zope.org mailing list. We're always looking for volunteers
wanting to help with the docs, so feel free to send a mail there!
@@ -18,9 +16,10 @@
* the `docutils <http://docutils.sf.net/>`_ project for creating
reStructuredText and the docutils suite;
-* Georg Brandl for his `sphinx` package.
+* Georg Brandl for his `Sphinx` package.
-See :ref:`reporting-bugs` for information how to report bugs in Python itself.
+See :ref:`reporting-bugs` for information how to report bugs in Grok
+itself.
.. including the ACKS file here so that it can be maintained separately
.. include:: ACKS.txt
@@ -32,18 +31,15 @@
The Grok documentation toolchain
================================
-Grok now makes use of the ``sphinx`` package, which was written by
+Grok now makes use of the ``Sphinx`` package, which was written by
Georg Brandl and volunteers, to generate the official Python
documentation. Sphinx is able to generate HTML as well as LaTeX and
-HTMLHelp formats. The latter is currently not supported by grokdocs.
+other formats.
-The ``grokdocs`` module provides wrappers for ``sphinx``.
-
How can I generate nice HTML/LaTeX/PDF documentation for Grok?
--------------------------------------------------------------
-
If you have run ``bin/buildout``, than you're nearly finished. This
will generate some scripts in the ``bin/`` directory. Just run::
@@ -53,22 +49,15 @@
docs/build/html/
-For LaTeX/PDF docs you must have LaTeX and ``pdflatex`` installed. If
-you want PDF docs, you have to perform two steps.
+For LaTeX/PDF docs you must have LaTeX and ``pdflatex`` installed. Then, to generate PDF docs, run::
-1) Run::
+ $ bin/grokdocs2pdf
- $ bin/grokdocs2latex
+which will first generate .tex files and appropriate Makefiles in
+``docs/build/latex`` and afterwards run ``pdflatex`` to generate PDFs.
- which will generate .tex files and appropriate Makefiles in
- ``docs/build/latex``.
+If everything works smoothly three documents will be generated:
-2) Then change to ``docs/buid/latex`` and do::
-
- $ make
-
-The latter will run `pdflatex` to generate three documents:
-
1) The Tutorial (``tutorial.pdf``)
2) The Reference (``reference.pdf``)
@@ -80,22 +69,27 @@
Any warnings during the document processing can be ignored for the
time being.
-You can run each of the scripts with the `-h` option to see other
-available options. The new documentation toolchain is basically able
-to build **any** documentation, not just the Grok documentation.
+The ``grokdocs2...`` scripts generated in ``bin/`` unfortunately yet
+do not accept much options. In fact they accept no options at all. But
+you can use the also generated script ``bin/sphinx-build`` to finetune
+parameters or, after running ``grokdocs2...`` change to the ``build/``
+directory and run for instance::
+ $ make html SPHINXOPTS="-E -a"
+to regenerate all docs in HTML format.
+
+
How to tweak the layout/settings of the documentation toolchain
---------------------------------------------------------------
-The general settings of documentation generated by ``sphinx`` and
-``grokdocs`` are settable in a file ``conf.py`` which must be in the
-source root directory of your docs. Have a look at ``docs/conf.py``
-for deeper insights.
+Beside passing options to Spinx (see above), the general settings of
+documentation generated by ``sphinx`` are settable in a file
+``conf.py`` which must be in the source root directory of your
+docs. Have a look at ``docs/conf.py`` for deeper insights.
The structure of the HTML entry page is defined in
``build/docindex.template``, which is a template for the Jinja
templating engine used by Sphinx.
The layout details are defined in ``docs/.static/grok.css``.
-
Modified: grok/trunk/doc/conf.py
===================================================================
--- grok/trunk/doc/conf.py 2010-12-30 11:29:05 UTC (rev 119219)
+++ grok/trunk/doc/conf.py 2010-12-30 12:02:25 UTC (rev 119220)
@@ -12,20 +12,10 @@
# show the default value as assigned to them.
import sys
+import pkg_resources
from os import path, curdir
-import re
-
-version = 'Unknown'
-setupfilepath = path.join(path.dirname(path.abspath(curdir)), 'setup.py')
-reg = re.compile("^\s*version = .(.+).,.*")
-for line in open(setupfilepath, 'r').read().split('\n'):
- m = reg.match(line)
- if m:
- version = m.groups()[0]
-
-
# If your extensions are in another directory, add it here.
#sys.path.append('some/directory')
@@ -33,9 +23,16 @@
# ---------------------
# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.addons.*') or your custom ones.
-#extensions = []
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc',
+ 'sphinx.ext.doctest',
+ 'sphinx.ext.intersphinx',
+ # 'sphinx.ext.viewcode', # This is currently broken?
+ ]
+# Order autodoc generated docs in source code order.
+autodoc_member_order = 'bysource'
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['.']
@@ -47,15 +44,17 @@
# General substitutions.
project = 'Official Grok'
-copyright = '2006-2009, The Zope Foundation'
+copyright = '2006-2010, The Zope Foundation'
# The default replacements for |version| and |release|, also used in various
# other places throughout the built documents.
#
# The short X.Y version.
-version = version
+version = pkg_resources.get_distribution('grok').version
# The full version, including alpha/beta/rc tags.
release = version
+if release.endswith('dev'):
+ release = '%s (unreleased)' % release
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
Modified: grok/trunk/doc/contents.rst
===================================================================
--- grok/trunk/doc/contents.rst 2010-12-30 11:29:05 UTC (rev 119219)
+++ grok/trunk/doc/contents.rst 2010-12-30 12:02:25 UTC (rev 119220)
@@ -15,4 +15,6 @@
bugs.rst
license.rst
+ README.rst
copyright.rst
+ glossary.rst
Modified: grok/trunk/doc/index.rst
===================================================================
--- grok/trunk/doc/index.rst 2010-12-30 11:29:05 UTC (rev 119219)
+++ grok/trunk/doc/index.rst 2010-12-30 12:02:25 UTC (rev 119220)
@@ -0,0 +1,7 @@
+Official Grok Documentation Overview
+************************************
+
+.. toctree::
+ :hidden:
+
+ contents.rst
Modified: grok/trunk/doc/reference/components.rst
===================================================================
--- grok/trunk/doc/reference/components.rst 2010-12-30 11:29:05 UTC (rev 119219)
+++ grok/trunk/doc/reference/components.rst 2010-12-30 12:02:25 UTC (rev 119220)
@@ -23,6 +23,11 @@
Core components
~~~~~~~~~~~~~~~
+.. module:: grok
+
+.. automodule:: grok.components
+ :members:
+
:class:`grok.Application`
=========================
@@ -31,32 +36,27 @@
data objects such as :class:`grok.Container` and :class:`grok.Model` object
instances.
-When a new Grok application is installed using the Grok Admin interface, it
-creates an instance of the :class:`grok.Application` class and saves it in
-the root of the main ZODB database.
+.. autoclass:: grok.Application
+ :members:
-.. class:: grok.Application
- Base class for applications. Inherits from :class:`grok.Site`.
-
-
:class:`grok.Model`
===================
Model objects provide persistence and containment. Model in Grok refers to
an applications data model - that is data which is persistently saved to
-disk, by default in the Zope Object Dataabse (ZODB).
+disk, by default in the Zope Object Database (ZODB).
-.. class:: grok.Model
+.. autoclass:: grok.Model
+ :members:
- Base class to define a content or model object.
-
.. attribute:: __parent__
The parent in the location hierarchy.
- If you recursively follow the `__parent__` attribute, you will always
- reach a reference to a top-level grok.Application object instance.
+ If you recursively follow the :attr:`__parent__` attribute, you
+ will always reach a reference to a top-level grok.Application
+ object instance.
.. attribute:: __name__
@@ -64,8 +64,9 @@
Traverse the parent with this name to get the object.
- Name in Grok means "human-readable identifier" as the `__name__`
- attribute is used to reference the object within an URL.
+ Name in Grok means "human-readable identifier" as the
+ :attr:`__name__` attribute is used to reference the object
+ within an URL.
:class:`grok.Container`
@@ -76,16 +77,15 @@
zope.container.interfaces.IContainer interface using a BTree, providing
reasonable performance for large collections of objects.
-.. class:: grok.Container
+.. autoclass:: grok.Container
- Base class to define a container object.
-
.. attribute:: __parent__
The parent in the location hierarchy.
- If you recursively follow the `__parent__` attribute, you will always
- reach a reference to a top-level grok.Application object instance.
+ If you recursively follow the :attr:`__parent__` attribute, you
+ will always reach a reference to a top-level grok.Application
+ object instance.
.. attribute:: __name__
@@ -93,8 +93,9 @@
Traverse the parent with this name to get the object.
- Name in Grok means "human-readable identifier" as the `__name__`
- attribute is used to reference the object within an URL.
+ Name in Grok means "human-readable identifier" as the
+ :attr:`__name__` attribute is used to reference the object
+ within an URL.
.. method:: items(key=None)
@@ -262,56 +263,24 @@
important to note that OrderedContainers will have poorer performance than
a normal Container.
-.. class:: grok.OrderedContainer
+.. autoclass:: grok.OrderedContainer
+ :members:
- Base class for an OrderedContainer. OrderedContainer inherits from
- Container and supports the same interface.
-
- .. method:: updateOrder(order)
-
- Revise the order of keys, replacing the current ordering.
- order is a list or a tuple containing the set of existing keys in
- the new order. `order` must contain ``len(keys())`` items and cannot
- contain duplicate keys.
+Indexes
+~~~~~~~
- Raises ``TypeError`` if order is not a tuple or a list.
-
- Raises ``ValueError`` if order contains an invalid set of keys.
-
-
:class:`grok.Indexes`
=====================
-Indexes are local utilities for holding a set of indexes alongside a
-:class:`grok.Site` or :class:`grok.Application`. An index is a data
-structure that provides a way of quickly finding certain types of
-objects, i.e. it provides catalog functionality for
+:class:`Indexes` are local utilities for holding a set of indexes
+alongside a :class:`grok.Site` or :class:`grok.Application`. An index
+is a data structure that provides a way of quickly finding certain
+types of objects, i.e. it provides catalog functionality for
attributes/contents of stored objects.
-The site or application that the indexes are intended for should be
-named with the :func:`grok.site()` directive, and the kind of object to
-index should be named with a :func:`grok.context()` directive.
+.. autodata:: grok.Indexes
-Inside their class, the developer should specify one or more
-:class:`grok.index.Field`, :class:`grok.index.Text`, or
-:class:`grok.index.Set` instances naming object attributes that should
-be indexed (and therefore searchable). See :mod:`grok.index` module
-for more information on field types.
-
-.. note:: Indexes are persistent: they are stored in the Zope database
- alongside the site or application that they index. They are
- created when the site or application is first created (and
- made persistent), and so an already-created site will not
- change just because the definition of one of its
- `grok.Indexes` changes; it will either have to be deleted
- and re-created, or some other operation performed to bring
- its indexes up to date.
-
-.. class:: grok.Indexes
-
- Base class for index collections in a Grok application.
-
**Directives:**
:func:`grok.context(context_obj_or_interface)`
@@ -331,6 +300,14 @@
:func:`grok.site`
+Grok Index Definitions
+======================
+
+.. automodule:: grok.index
+ :members:
+ :inherited-members:
+ :undoc-members:
+
**Example 1: Index the Mammoths in a Herd**
Imagine you have a herd of mammoths, and you wish to quickly find a
@@ -397,6 +374,8 @@
Adapters
~~~~~~~~
+.. currentmodule:: grok
+
:class:`grok.Adapter`
=====================
@@ -413,18 +392,21 @@
def __init__(self, context):
self.context = context
-.. class:: grok.Adapter
+.. autoclass:: grok.Adapter
+ :members:
+ .. The Adapter class itself does not provide docstrings.
+
Base class to define an adapter. Adapters are automatically
registered when a module is "grokked".
- .. attribute:: grok.Adapter.context
+ .. attribute:: context
The adapted object.
**Directives:**
- :func:`grok.context(context_obj_or_interface)`
+ :data:`grok.context(context_obj_or_interface)`
Maybe required. Identifies the type of objects or interface for
the adaptation.
@@ -432,14 +414,14 @@
:func:`grok.context`
- :func:`grok.implements(\*interfaces)`
+ :data:`grok.implements(\*interfaces)`
Required. Identifies the interface(s) the adapter implements.
.. seealso::
:func:`grok.implements`
- :func:`grok.name(name)`
+ :data:`grok.name(name)`
Optional. Identifies the name used for the adapter
registration. If ommitted, no name will be used.
@@ -457,6 +439,7 @@
:func:`grok.provides`
+
**Example 1: Simple adaptation example**
.. code-block:: python
@@ -514,34 +497,35 @@
A MultiAdapter takes multiple objects providing existing interface(s)
and extends them to provide a new interface.
-The `grok.MultiAdapter` base class does not provide a default constructor
-implementation, it's up to the individual multi-adapters to determine how
-to handle the objects being adapted.
+The :class:`grok.MultiAdapter` base class does not provide a default
+constructor implementation, it's up to the individual multi-adapters
+to determine how to handle the objects being adapted.
-.. class:: grok.MultiAdapter
+.. autoclass:: grok.MultiAdapter
+ :members:
Base class to define a Multi Adapter.
**Directives:**
- :func:`grok.adapts(\*objects_or_interfaces)`
+ :data:`grok.adapts(\*objects_or_interfaces)`
Required. Identifies the combination of types of objects or interfaces
for the adaptation.
- :func:`grok.implements(\*interfaces)`
+ :data:`grok.implements(\*interfaces)`
Required. Identifies the interfaces(s) the adapter implements.
- :func:`grok.name(name)`
+ :data:`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.
+ When a name is used for the adapter registration, the adapter
+ can only be retrieved by explicitely using its name.
- :func:`grok.provides(name)`
- Only required if the adapter implements more than one interface.
- :func:`grok.provides` is required to disambiguate for which interface the
- adapter will be registered for.
+ :data:`grok.provides(name)`
+ Only required if the adapter implements more than one
+ interface. :func:`grok.provides` is required to disambiguate
+ for which interface the adapter will be registered for.
**Example: A home is made from a cave and a fireplace.**
@@ -574,11 +558,11 @@
.. code-block:: python
- def FireplaceView(grok.View):
+ class FireplaceView(grok.View):
grok.context(Fireplace)
grok.name('fire-view')
-
- def AlternateFireplaceView(grok.View):
+
+ class AlternateFireplaceView(grok.View):
grok.context(Fireplace)
def render(self):
@@ -593,11 +577,12 @@
Annotation components are persistent writeable adapters.
-.. class:: grok.Annotation
+.. autoclass:: grok.Annotation
+ :members:
- Base class to declare an Annotation. Inherits from the
- persistent.Persistent class.
+ Inherits from the :class:`persistent.Persistent` class.
+
**Example: Storing annotations on model objects**
.. code-block:: python
@@ -647,27 +632,28 @@
Examples of global utilities are database connections, XML parsers,
and web service proxies.
-.. class:: grok.GlobalUtility
+.. autoclass:: grok.GlobalUtility
+ :members:
Base class to define a globally registered utility. Global utilities are
automatically registered when a module is "grokked".
**Directives:**
- :func:`grok.implements(\*interfaces)`
+ :data:`grok.implements(\*interfaces)`
Required. Identifies the interfaces(s) the utility implements.
- :func:`grok.name(name)`
+ :data:`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.
+ :data:`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.LocalUtility`
@@ -683,34 +669,37 @@
where you need to dynamically provide the connection settings
so that they can be edited through-the-web.
-.. class:: grok.LocalUtility
+.. autoclass:: grok.LocalUtility
+ :members:
- 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.
+ Defines utilities 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)`
+ :data:`grok.implements(\*interfaces)`
Optional. Identifies the interfaces(s) the utility implements.
- :func:`grok.name(name)`
+ :data:`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.
+ 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.
+ :data:`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.
+ 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.Site`
==================
@@ -723,39 +712,36 @@
manager to delegate to. If no other site manager is found they defer to
the global site manager which contains file based utilities and adapters.
-.. class:: grok.Site
+.. autoclass:: grok.Site
+ :members:
- .. method:: getSiteManager()
+ .. automethod:: grok.Site.getSiteManager()
- Returns the site manager contained in this object.
+ Returns the site manager contained in this object.
- If there isn't a site manager, raise a component lookup.
+ If there isn't a site manager, raise a component lookup.
- .. method:: setSiteManager(sitemanager)
-
- Sets the site manager for this object.
+ .. automethod:: grok.Site.setSiteManager(sitemanager)
+ Sets the site manager for this object.
+
Views
~~~~~
:class:`grok.View`
==================
-Views handle interactions between the user and the model. The are constructed
-with context and request attributes, are responsible for providing a
-response. The request attribute in a View will always be for a normal
-HTTP Request.
+Views handle interactions between the user and the model. The are
+constructed with context and request attributes, are responsible for
+providing a response. The request attribute in a View will always be
+for a normal HTTP Request.
-The determination of what View gets used for what Model is made by walking the
-URL in the HTTP Request object sepearted by the / character. This process is
-called Traversal.
+The determination of what :class:`View` gets used for what
+:class:`Model` is made by walking the URL in the HTTP Request object
+sepearted by the ``/`` character. This process is called "Traversal".
-.. class:: grok.View
+.. autoclass:: grok.View
- Base class to define a View.
-
- Implements the `grokcore.view.interfaces.IGrokView` interface.
-
.. attribute:: context
The object that the view is presenting. This is often an instance of
@@ -766,24 +752,46 @@
The HTTP Request object.
- .. attribute:: response
+ .. autoattribute:: grok.View.response
- The HTTP Response object that is associated with the request. This
- is also available as self.request.response, but the response attribute
- is provided as a convenience.
+ The HTTP Response object that is associated with the request.
+ This is also available as ``self.request.response``, but the
+ response attribute is provided as a convenience.
+
.. attribute:: static
- Directory resource containing the static files of the view's package.
+ Directory resource containing the static files of the view's
+ package.
- .. method:: redirect(url)
-
- Redirect to given URL
+ .. autoattribute:: grok.View.body
- .. method:: url(obj=None, name=None, data=None)
-
- Construct URL.
+ Get the body of the associated request.
+ .. automethod:: grok.View.redirect
+
+ Redirect to `url`.
+
+ The headers of the :attr:`response` are modified so that the
+ calling browser gets a redirect status code. Please note, that
+ this method returns before actually sending the response to
+ the browser.
+
+ `url` is a string that can contain anything that makes sense
+ to a browser. Also relative URIs are allowed.
+
+ `status` is a number representing the HTTP status code sent
+ back. If not given or ``None``, ``302`` or ``303`` will be
+ sent, depending on the HTTP protocol version in use (HTTP/1.0
+ or HTTP/1.1).
+
+ `trusted` is a boolean telling whether we're allowed to
+ redirect to 'external' hosts. Normally redirects to other
+ hosts than the one the request was sent to are forbidden and
+ will raise a :exc:`ValueError`.
+
+ .. automethod:: grok.View.url
+
If no arguments given, construct URL to view itself.
If only obj argument is given, construct URL to obj.
@@ -794,28 +802,25 @@
If both object and name arguments are supplied, construct
URL to obj/name.
- Optionally pass a 'data' keyword argument which gets added to the URL
- as a cgi query string.
+ .. automethod:: grok.View.default_namespace
- .. method:: default_namespace()
-
Returns a dictionary of namespaces that the template
implementation expects to always be available.
This method is *not* intended to be overridden by application
developers.
- .. method:: namespace()
-
+ .. automethod:: grok.View.namespace
+
Returns a dictionary that is injected in the template
namespace in addition to the default namespace.
This method *is* intended to be overridden by the application
developer.
- .. method:: update(**kw)
-
- This method is meant to be implemented by grok.View
+ .. automethod:: grok.View.update
+
+ This method is meant to be implemented by :class:`grok.View`
subclasses. It will be called *before* the view's associated
template is rendered and can be used to pre-compute values
for the template.
@@ -824,8 +829,8 @@
filled in from the request (in that case they *must* be
present in the request).
- .. method:: render(**kw)
-
+ .. automethod:: grok.View.render
+
A view can either be rendered by an associated template, or
it can implement this method to render itself from Python.
This is useful if the view's output isn't XML/HTML but
@@ -835,17 +840,12 @@
filled in from the request (in that case they *must* be
present in the request).
- .. method:: application_url(name=None)
-
- Return the URL of the closest application object in the
- hierarchy or the URL of a named object (``name`` parameter)
- relative to the closest application object.
+ .. automethod:: grok.View.application_url
- .. method:: flash(message, type='message')
-
- Send a short message to the user.
+ .. automethod:: grok.View.flash
+
:class:`grok.ViewletManager`
============================
@@ -867,34 +867,52 @@
ViewletManager's also implement a read-only mapping API, so the Viewlet's
that they contain can be read like a normal Python dictionary.
-.. class:: grok.ViewletManager
+.. autoclass:: grok.ViewletManager
- Base class for a ViewletManager.
-
- .. attribute:: context
+ .. XXX: undocumented: sort(), filter(), get().
- Typically the Model object for which this ViewletManager is being
- rendered in the context of.
+ .. attribute:: context
+
+ Typically the Model object for which this ViewletManager is being
+ rendered in the context of.
- .. attribute:: request
+ .. attribute:: request
- The Request object.
+ The Request object.
- .. attribute:: view
+ .. attribute:: view
- Reference to the View that the ViewletManager is being provided in.
+ Reference to the View that the ViewletManager is being provided
+ in.
- .. method:: update()
+ .. automethod:: grok.ViewletManager.default_namespace
- This method is called before the ViewletManager is rendered, and
- can be used to perfrom pre-computation.
-
- .. method:: render(*args, **kw)
+ Returns a dictionary of namespaces that the template
+ implementation expects to always be available.
- This method renders the content provided by this ViewletManager.
- Typically this will mean rendering and concatenating all of the
- Viewlets managed by this ViewletManager.
+ This method is *not* intended to be overridden by application
+ developers.
+ .. automethod:: grok.ViewletManager.namespace
+
+ Returns a dictionary that is injected in the template
+ namespace in addition to the default namespace.
+
+ This method *is* intended to be overridden by the application
+ developer.
+
+ .. automethod:: grok.ViewletManager.update
+
+ This method is called before the ViewletManager is rendered, and
+ can be used to perform pre-computation.
+
+ .. automethod:: grok.ViewletManager.render
+
+ This method renders the content provided by this ViewletManager.
+ Typically this will mean rendering and concatenating all of the
+ Viewlets managed by this ViewletManager.
+
+
**Example: Register a ViewletManager and Viewlet and use them from a template for a View**
This is a very simple example, ViewletManagers and Viewlets can be used to
@@ -935,10 +953,9 @@
pages of the site have the same layout with header, one or two columns, the
main content area and a footer.
-.. class:: grok.Viewlet
+.. autoclass:: grok.Viewlet
+ :members:
- Base class for a Viewlet.
-
.. attribute:: context
Typically the Model object for which this Viewlet is being
@@ -955,13 +972,29 @@
.. attribute:: viewletmanager
Reference to the ViewletManager that is rendering this Viewlet.
-
- .. method:: update()
+ .. automethod:: grok.Viewlet.default_namespace
+
+ Returns a dictionary of namespaces that the template
+ implementation expects to always be available.
+
+ This method is *not* intended to be overridden by application
+ developers.
+
+ .. automethod:: grok.Viewlet.namespace
+
+ Returns a dictionary that is injected in the template
+ namespace in addition to the default namespace.
+
+ This method *is* intended to be overridden by the application
+ developer.
+
+ .. automethod:: grok.Viewlet.update
+
This method is called before the Viewlet is rendered, and
can be used to perfrom pre-computation.
- .. method:: render(*args, **kw)
+ .. automethod:: grok.Viewlet.render
This method renders the content provided by this Viewlet.
@@ -977,10 +1010,76 @@
begin with an _ or special names such as __call__. The grok.require
decorator can be used to protect methods with a permission.
-.. class:: grok.JSON
+.. autoclass:: grok.JSON
- Base class for JSON methods.
+ .. attribute:: context
+
+ Object that the JSON handler presents.
+ .. attribute:: request
+
+ Request that JSON handler was looked up with.
+
+ .. autoattribute:: response
+
+ The response sent back to the client.
+
+ .. attribute:: body
+
+ The text of the request body.
+
+ .. automethod:: redirect
+
+ Redirect to `url`.
+
+ The headers of the :attr:`response` are modified so that the
+ calling browser gets a redirect status code. Please note, that
+ this method returns before actually sending the response to
+ the browser.
+
+ `url` is a string that can contain anything that makes sense
+ to a browser. Also relative URIs are allowed.
+
+ `status` is a number representing the HTTP status code sent
+ back. If not given or ``None``, ``302`` or ``303`` will be
+ sent, depending on the HTTP protocol version in use (HTTP/1.0
+ or HTTP/1.1).
+
+ `trusted` is a boolean telling whether we're allowed to
+ redirect to 'external' hosts. Normally redirects to other
+ hosts than the one the request was sent to are forbidden and
+ will raise a :exc:`ValueError`.
+
+ .. automethod:: url
+
+ .. automethod:: publishTraverse
+
+ Lookup a name and return an object with `self.context` as its parent.
+ The method can use the request to determine the correct object.
+
+ The `request` argument is the publisher request object. The
+ `name` argument is the name that is to be looked up. It must
+ be an ASCII string or Unicode object.
+
+ If a lookup is not possible, raise a :exc:`NotFound` error.
+
+ .. automethod:: browserDefault
+
+ Returns an object and a sequence of names.
+
+ The publisher calls this method at the end of each traversal path.
+ If the sequence of names is not empty, then a traversal step is made
+ for each name. After the publisher gets to the end of the sequence,
+ it will call browserDefault on the last traversed object.
+
+ The default behaviour in Grok is to return `self.context` for
+ the object and ``'index'`` for the default view name.
+
+ Note that if additional traversal steps are indicated (via a
+ nonempty sequence of names), then the publisher will try to adjust
+ the base href.
+
+
**Example 1: Create a public and a protected JSON view.**
.. code-block:: python
@@ -1010,10 +1109,8 @@
These Views can define methods named GET, PUT, POST and DELETE, which will
be invoked based on the Request type.
-.. class:: grok.REST
+.. autoclass:: grok.REST
- Base class for REST.
-
.. attribute:: context
Object that the REST handler presents.
@@ -1022,20 +1119,71 @@
Request that REST handler was looked up with.
- .. attribute:: body
+ .. autoattribute:: response
+
+ The response sent back to the client.
+
+ .. autoattribute:: body
The text of the request body.
+ .. automethod:: application_url
+ .. automethod:: url
+
+ .. automethod:: redirect
+
+ Redirect to `url`.
+
+ The headers of the :attr:`response` are modified so that the
+ calling browser gets a redirect status code. Please note, that
+ this method returns before actually sending the response to
+ the browser.
+
+ `url` is a string that can contain anything that makes sense
+ to a browser. Also relative URIs are allowed.
+
+ `status` is a number representing the HTTP status code sent
+ back. If not given or ``None``, ``302`` or ``303`` will be
+ sent, depending on the HTTP protocol version in use (HTTP/1.0
+ or HTTP/1.1).
+
+ `trusted` is a boolean telling whether we're allowed to
+ redirect to 'external' hosts. Normally redirects to other
+ hosts than the one the request was sent to are forbidden and
+ will raise a :exc:`ValueError`.
+
+
:class:`grok.XMLRPC`
====================
Specialized View that responds to XML-RPC.
-.. class:: grok.XMLRPC
+.. autoclass:: grok.XMLRPC
- Base class for XML-RPC methods.
+ .. attribute:: context
+
+ Object that the REST handler presents.
+ .. attribute:: request
+
+ Request that REST handler was looked up with.
+
+ .. autoattribute:: grok.XMLRPC.response
+
+ The response sent back to the client.
+
+ .. autoattribute:: grok.XMLRPC.body
+
+ The text of the request body.
+
+ .. automethod:: grok.XMLRPC.application_url
+
+ .. automethod:: grok.XMLRPC.url
+
+ .. automethod:: grok.XMLRPC.redirect
+
+
**Example 1: Create a public and a protected XML-RPC view.**
The grok.require decorator can be used to protect methods with a permission.
@@ -1062,10 +1210,10 @@
A Traverser is used to map from a URL to an object being published (Model)
and the View used to interact with that object.
-.. class:: grok.Traverser
+.. autoclass:: grok.Traverser
- Base class for custom traversers. Override the traverse method to
- supply the desired custom traversal behaviour.
+ Override the :meth:`traverse` method to supply the desired custom
+ traversal behaviour.
.. attribute:: context
@@ -1075,14 +1223,14 @@
The HTTP Request object.
- .. method:: traverse(self, name):
-
- You must provide your own implementation of this method to do what
- you want. If you return None, Grok will use the default traversal
- behaviour.
+ .. automethod:: traverse
- .. method:: browserDefault(request):
-
+ You must provide your own implementation of this method to do
+ what you want. If you return ``None``, Grok will use the
+ default traversal behaviour.
+
+ .. automethod:: browserDefault
+
Returns an object and a sequence of names.
The publisher calls this method at the end of each traversal path.
@@ -1090,24 +1238,25 @@
for each name. After the publisher gets to the end of the sequence,
it will call browserDefault on the last traversed object.
- The default behaviour in Grok is to return self.context for the object
- and 'index' for the default view name.
+ The default behaviour in Grok is to return `self.context` for
+ the object and ``'index'`` for the default view name.
Note that if additional traversal steps are indicated (via a
nonempty sequence of names), then the publisher will try to adjust
the base href.
- .. method:: publishTraverse(request, name):
+ .. automethod:: publishTraverse
- Lookup a name and return an object with `self.context` as it's parent.
+ Lookup a name and return an object with `self.context` as its parent.
The method can use the request to determine the correct object.
- The 'request' argument is the publisher request object. The
- 'name' argument is the name that is to be looked up. It must
+ The `request` argument is the publisher request object. The
+ `name` argument is the name that is to be looked up. It must
be an ASCII string or Unicode object.
-
- If a lookup is not possible, raise a NotFound error.
+ If a lookup is not possible, raise a :exc:`NotFound` error.
+
+
**Example 1: Traverse into a Herd Model and return a Mammoth Model**
.. code-block:: python
@@ -1142,17 +1291,25 @@
grok.PageTemplate("<h1>Hello World!</h1>")
-.. class:: grok.PageTemplate
+.. autoclass:: grok.PageTemplate
- .. method:: _initFactory(factory)
-
+ .. automethod:: grok.PageTemplate._initFactory
+
Template language specific initializations on the view factory.
- .. method:: render(view)
-
- Renders the template
+ .. automethod:: grok.PageTemplate.render
+ Renders the template.
+ .. automethod:: grok.PageTemplate.setFromString
+
+ .. automethod:: grok.PageTemplate.setFromFilename
+
+ .. automethod:: grok.PageTemplate.getNamespace
+
+ .. automethod:: grok.PageTemplate.namespace
+
+
:class:`grok.PageTemplateFile`
==============================
@@ -1162,44 +1319,59 @@
grok.PageTemplateFile("my_page_template.pt")
-.. class:: grok.PageTemplateFile
+.. autoclass:: grok.PageTemplateFile
- .. method:: _initFactory(factory)
+ .. automethod:: grok.PageTemplateFile._initFactory
Template language specific initializations on the view factory.
- .. method:: render(view)
-
- Renders the template
+ .. automethod:: grok.PageTemplateFile.render
+ Renders the template.
+ .. automethod:: grok.PageTemplateFile.setFromString
+
+ .. automethod:: grok.PageTemplateFile.setFromFilename
+
+ .. automethod:: grok.PageTemplateFile.getNamespace
+
+ .. automethod:: grok.PageTemplateFile.namespace
+
+
+
Forms
~~~~~
-Forms inherit from the `grok.View` class. They are a specialized type of
+Forms inherit from the :class:`grok.View` class. They are a specialized type of
View that renders an HTML Form.
:class:`grok.Form`
==================
-.. class:: grok.Form
+.. autoclass:: grok.Form
- Base class for forms.
+ .. attribute:: template
+
+ Template used to display the form
+ .. attribute:: context
+
+ The object for which the form is rendered.
+
.. attribute:: prefix
Page-element prefix. All named or identified page elements in a
subpage should have names and identifiers that begin with a subpage
prefix followed by a dot.
- .. method:: setPrefix(prefix):
+ .. automethod:: setPrefix
Update the subpage prefix
.. attribute:: label
A label to display at the top of a form.
-
+
.. attribute:: status
An update status message. This is normally generated by success or
@@ -1227,42 +1399,47 @@
The form's widgets.
- - set by setUpWidgets
+ - set by :meth:`setUpWidgets`
- - used by validate
+ - used by :meth:`validate`
+ .. autoattribute:: actions
- .. method:: setUpWidgets(ignore_request=False):
+ .. autoattribute:: body
+
+ The text of the request body.
+
+ .. autoattribute:: response
+
+ The response sent back to the client.
+
+ .. automethod:: setUpWidgets
Set up the form's widgets.
The default implementation uses the form definitions in the
- form_fields attribute and setUpInputWidgets.
+ :attr:`form_fields` attribute and :meth:`setUpInputWidgets`.
- The function should set the widgets attribute.
+ The function should set the :attr:`widgets` attribute.
- .. method:: validate(action, data):
+ .. automethod:: validate
The default form validator
If an action is submitted and the action doesn't have it's own
validator then this function will be called.
- .. attribute:: template
+ .. automethod:: resetForm
- Template used to display the form
-
- .. method:: resetForm():
-
Reset any cached data because underlying content may have changed.
- .. method:: error_views():
+ .. automethod:: grok.Form.error_views
Return views of any errors.
The errors are returned as an iterable.
- .. method:: applyData(obj, **data):
+ .. automethod:: applyData
Save form data to an object.
@@ -1272,35 +1449,73 @@
the method works in update mode (e.g. on EditForms) and
doesn't have to update an object, the dictionary is empty.
+ .. automethod:: application_url
+
+ .. automethod:: applyChanges
+
+ .. deprecated:: 0.13
+ Use :meth:`applyData` instead.
+
+ .. automethod:: availableActions
+
+ .. automethod:: browserDefault
+
+ .. automethod:: default_namespace
+
+ .. automethod:: flash
+
+ .. automethod:: namespace
+
+ .. automethod:: publishTraverse
+
+ .. automethod:: redirect
+
+ .. automethod:: render
+
+ .. automethod:: update
+
+ .. automethod:: update_form
+
+ .. automethod:: url
+
+
:class:`grok.AddForm`
=====================
Add forms are used for creating new objects. The widgets for this form
are not bound to any existing content or model object.
-.. class:: grok.AddForm
+.. autoclass:: grok.AddForm
+ :members:
+ :undoc-members:
- Base class for add forms. Inherits from :class:`grok.Form`.
+ Inherits from :class:`grok.Form`.
+
:class:`grok.EditForm`
======================
Edit forms are used for editing existing objects. The widgets for this form
are bound to the object set in the `context` attribute.
-.. class:: grok.EditForm
+.. autoclass:: grok.EditForm
+ :members:
+ :undoc-members:
- Base class for edit forms. Inherits from :class:`grok.Form`.
+ Inherits from :class:`grok.Form`.
+
:class:`grok.DisplayForm`
=========================
Display forms are used to display an existing object. The widgets for this
form are bound to the object set in the `context` attribute.
-.. class:: grok.DisplayForm
+.. autoclass:: grok.DisplayForm
+ :members:
+ :undoc-members:
- Base class for display forms. Inherits from :class:`grok.Form`.
+ Inherits from :class:`grok.Form`.
Security
@@ -1309,22 +1524,24 @@
:class:`grok.Permission`
========================
-Permissions are used to protect Views so that they can only be called by
-an authenticated principal. If a View in Grok does not have a `grok.require`
-directive declaring a permission needed to use the View, then the default
-anonymously viewable `zope.View` permission used.
+Permissions are used to protect Views so that they can only be called
+by an authenticated principal. If a View in Grok does not have a
+:func:`grok.require` directive declaring a permission needed to use
+the View, then the default anonymously viewable `zope.View` permission
+used.
-.. class:: grok.Permission
+.. autoclass:: grok.Permission
- Base class for permissions. You must specify a unique name for every
- permission using the `grok.name` directive. The convention for ensuring
- uniqueness is to prefix your permission name with the name of your
- Grok package followed by a dot, e.g. 'mypackage.MyPermissionName'.
+ Base class for permissions. You must specify a unique name for
+ every permission using the :func:`grok.name` directive. The convention
+ for ensuring uniqueness is to prefix your permission name with the
+ name of your Grok package followed by a dot,
+ e.g. ``'mypackage.MyPermissionName'``.
.. attribute:: id
Id as which this permission will be known and used. This is set
- to the value specified in the `grok.name` directive.
+ to the value specified in the :func:`grok.name` directive.
.. attribute:: title
@@ -1336,19 +1553,20 @@
**Directives:**
- :func:`grok.name(name)`
+ :data:`grok.name(name)`
Required. Identifies the unique name (also used as the id) of the
permission.
- :func:`grok.title(title)`
+ :data:`grok.title(title)`
Optional. Stored as the title attribute for this permission.
- :func:`grok.description(description)`
+ :data:`grok.description(description)`
Optional. Stored as the description attribute for this permission.
+
**Example 1: Define a new Permission and use it to protect a View**
.. code-block:: python
@@ -1371,42 +1589,43 @@
(aka Users) can be granted a Role which will allow them to access all Views
protected by the Permissions that the Role contains.
-.. class:: grok.Role
+.. autoclass:: grok.Role
+ :members:
+ :inherited-members:
+ :undoc-members:
- Base class for roles.
-
- .. attribute:: id
+ .. attribute:: id
- Id as which this role will be known and used. This is set
- to the value specified in the `grok.name` directive.
+ Id as which this role will be known and used. This is set
+ to the value specified in the :func:`grok.name` directive.
- .. attribute:: title
+ .. attribute:: title
- Human readable identifier for this permission.
+ Human readable identifier for this permission.
- .. attribute:: description
+ .. attribute:: description
- Description of the permission.
+ Description of the permission.
- **Directives:**
+ **Directives:**
- :func:`grok.name(name)`
+ :data:`grok.name(name)`
- Required. Identifies the unique name (also used as the id) of the
- role.
+ Required. Identifies the unique name (also used as the id) of the
+ role.
- :func:`grok.permissions(permissions)`
+ :data:`grok.permissions(permissions)`
- Required. Declare the permissions granted to this role. These
- can refer by permission class or by name.
+ Required. Declare the permissions granted to this role. These
+ can refer by permission class or by name.
- :func:`grok.title(title)`
+ :data:`grok.title(title)`
- Optional. Stored as the title attribute for this role.
+ Optional. Stored as the title attribute for this role.
- :func:`grok.description(description)`
+ :data:`grok.description(description)`
- Optional. Stored as the description attribute for this role.
+ Optional. Stored as the description attribute for this role.
**Example 1: Define a new 'paint.Artist' Role and assign it to the 'paint.grok' principal**
@@ -1472,4 +1691,4 @@
# but could also be a container within your application.
from zope.securitypolicy.interfaces import IPrincipalRoleManager
IPrincipalRoleManager(app).assignRoleToPrincipal(
- 'paint.Artixt', 'paint.grok')
+ 'paint.Artist', 'paint.grok')
Modified: grok/trunk/doc/reference/functions.rst
===================================================================
--- grok/trunk/doc/reference/functions.rst 2010-12-30 11:29:05 UTC (rev 119219)
+++ grok/trunk/doc/reference/functions.rst 2010-12-30 12:02:25 UTC (rev 119220)
@@ -79,7 +79,7 @@
:func:`grok.getApplication`
-====================
+===========================
.. function:: grok.getApplication()
Modified: grok/trunk/doc/reference/testing.rst
===================================================================
--- grok/trunk/doc/reference/testing.rst 2010-12-30 11:29:05 UTC (rev 119219)
+++ grok/trunk/doc/reference/testing.rst 2010-12-30 12:02:25 UTC (rev 119220)
@@ -281,223 +281,64 @@
then use the name `test_suite` in all matching modules as the object to
provide test suites.
-To make it easier to automatically discover tests and group them into
-different test suites, Grok provides a function for registering all
-tests.
+Test Supporting API
+~~~~~~~~~~~~~~~~~~~
-Automatic test detection and setup supports three kinds of tests:
+.. .. module:: grok.testing
- * **python tests:** Python modules which contain
- ``unittest.TestCase`` classes.
+To support testing in Grok-based projects, Grok comes with a couple of
+helpers located in the :mod:`grok.testing` module.
- * **unit doctests:** plain-text files that are written as doctests,
- but require no complicated layer setup.
+.. automodule:: grok.testing
+ :members:
+ :undoc-members:
+ :inherited-members:
- * **functional doctests:** plain-text files that are written as doctests,
- but also require the full Zope 3/Grok framework to test for example
- browser requests.
+ .. autofunction:: grok.testing.grok_component
+ Grok a single component.
-:func:`grok.testing.register_all_tests` -- automatically find all test cases
-============================================================================
+ This function can be used to grok individual components within a
+ doctest, such as adapters. It sets up just enough context for
+ some grokking to work, though more complicated grokkers which
+ need module context (such as view grokkers) might not work.
-.. function:: grok.testing.register_all_tests(package_name, *args, **kw)
+ Returns ``True`` or ``False`` depending on whether the grokking
+ worked or not.
- Get all functional, unit and python tests specified in the package
- name and return them as a test suite.
-
- Positional and keyword arguments will be passed to the TestSetups only
- if they are appropriate to the individual TestSetups. The keyword
- parameters are:
+ A sample doctest could look as follows:
- `filter_func`
-
- A function that takes an absolute filepath and retur - (.*)ns `True` or
- `False`, depending on whether the file should be included in the
- test suite as doctest or not. `filter_func` applies only to
- doctests.
-
- `extensions`
+ This defines the object we want to provide an adapter for:
- A list of filename extensions to be considered during test
- search. Default value is `['.txt', '.rst']`. Python tests are not
- touched by this (they have to be regular Python modules with '.py'
- extension).
-
- `encoding`
-
- The encoding of testfiles. 'utf-8' by default. Setting this to `None`
- means using the default value.
-
- `checker`
-
- An output checker for functional doctests.
-
- `globs`
-
- A dictionary of things that should be available immediately
- (without imports) during tests. Defaults are:
+ >>> class Bar(object):
+ ... pass
- .. code-block:: python
-
- dict(http=HTTPCaller(),
- getRootFolder=getRootFolder,
- sync=sync)
+ This is the interface that we want to adapt to:
- for functional doctests and an empty dict for unit
- doctests. Python test globals can't be set this way.
-
- If you want to register special globals for functional doctest or
- unit doctests only, then you can use the `fglobs` and/or `uglobs`
- keyword respectively. These keywords replace any `globs` value for
- the respective kind of tests.
-
- `setup`
-
- A function that takes a `test` argument and is executed before
- every single doctest. By default it runs::
+ >>> from zope.interface import Interface
+ >>> class IFoo(Interface):
+ ... pass
- zope.app.testing.functional.FunctionalTestSetup().setUp()
+ This is the adapter itself:
- for functional doctests and an empty function for unit
- doctests. Python tests provide their own setups.
+ >>> import grokcore.component as grok
+ >>> class MyAdapter(grok.Adapter):
+ ... grok.provides(IFoo)
+ ... grok.context(Bar)
- If you want to register special setup-functions for either
- functional or unit doctests, then you can pass keyword parameters
- `fsetup` or `usetup` respectively.
-
- `teardown`
-
- The equivalent to `setup`. Runs by default::
+ Now we will register the adapter using grok_component():
- FunctionalTestSetup().tearDown()
+ >>> from grok.testing import grok, grok_component
+ >>> grok('grokcore.component.meta')
+ >>> grok_component('MyAdapter', MyAdapter)
+ True
+
+ The adapter should now be available:
- for functional doctests and::
+ >>> adapted = IFoo(Bar())
+ >>> isinstance(adapted, MyAdapter)
+ True
- zope.testing.cleanup.cleanUp()
- for unit doctests. Python tests have to provide their own teardown
- functions in TestCases.
-
- `optionflags`
-
- Optionflags influence the behaviour of the testrunner. They are
- logically or'd so that you can add them arithmetically.
-
- `zcml_config`
-
- A filepath of a ZCML file which is registered with functional
- doctests. In the ZCML file you can for example register principals
- (users) usable by functional doctests.
-
- By default any `ftesting.zcml` file from the root of the given
- package is taken. If this does not exist, an empty ZCML file of
- the z3c.testsetup package is used (``ftesting.zcml``).
-
- This parameter has no effect, if also a ``layer`` parameter is
- given.
-
- `layer_name`
-
- You can name your layer, to distinguish different setups of
- functional doctests. The layer name can be an arbitrary string.
-
- This parameter has no effect, if also a ``layer`` parameter is
- given.
-
- `layer`
-
- You can register a ZCML layer yourself and pass it as the
- ``layer`` parameter. If you only have a filepath to the according
- ZCML file, use the ``zcml_config`` paramter instead.
-
- This parameter overrides any ``zcml_config`` and ``layer_name``
- parameter.
-
-
-**Example 1: Boilerplace code put into a tests.py module of a package**
-
-.. code-block:: python
-
- import grok
- test_suite = grok.testing.register_all_tests('sample')
-
-
-Python test layer
-=================
-
-The declaration `:Test-Layer: python` states the file should be included
-as part of the Python test layer. These modules are expected to contain
-``unittest.TestCase`` classes.
-
-**Example 1: Simple Python test**
-
-.. code-block:: python
-
- """
- Do a Python test on the app.
-
- :Test-Layer: python
- """
-
- import unittest
- from sample.app import Sample
-
- class SimpleSampleTest(unittest.TestCase):
- "Test the Sample application"
-
- def test1(self):
- "Test that something works"
- grokapp = Sample()
- self.assertEqual(list(grokapp.keys()), [])
-
-Unit test layer
-===============
-
-The declaration `:Test-Layer: unit` states the file should be included
-as part of the doctesting unit test layer. This layer requires no setup
-and is for tests which can be quickly run.
-
-**Example 1: Simple doctest**::
-
- Do a simple doctest test on the app.
- ************************************
- :Test-Layer: unit
-
- When you create an instance there are no objects in it::
-
- >>> from sample.app import Sample
- >>> grokapp = Sample()
- >>> list(grokapp.keys())
- []
-
-
-Functional test layer
-=====================
-
-The declaration `:Test-Layer: function` states the file should be included
-as part of the functional test layer. The setup for this layer includes a
-running Zope 3/Grok server. By default the ``ftesting.zcml`` file in the
-test package will be used to do configuration of your functional environment.
-
-**Example 1: Simple functional test**
-
-.. code-block:: python
-
- """
- Do a functional test on the app.
-
- :Test-Layer: python
- """
- from sample.app import Sample
- from sample.testing import FunctionalLayer
- from zope.app.testing.functional import FunctionalTestCase
- class SampleFunctionalTest(FunctionalTestCase):
- layer = FunctionalLayer
- class SimpleSampleFunctionalTest(SampleFunctionalTest):
- """ This the app in ZODB. """
- def test_simple(self):
- """ test creating a Sample instance into Zope """
- root = self.getRootFolder()
- root['instance'] = Sample()
- self.assertEqual(root.get('instance').__class__, Sample)
+ .. deprecated:: 1.0
+ Use :func:`grokcore.component.testing.grok_component` instead.
\ No newline at end of file
Modified: grok/trunk/doc/upgrade.txt
===================================================================
--- grok/trunk/doc/upgrade.txt 2010-12-30 11:29:05 UTC (rev 119219)
+++ grok/trunk/doc/upgrade.txt 2010-12-30 12:02:25 UTC (rev 119220)
@@ -96,7 +96,7 @@
.. _upgrade_notes_1.1rc1:
Upgrading to 1.1rc1 (2010-02-25)
--------------------------------
+--------------------------------
* When upgrading to a newer version of Grok, you should refer to the
newest list of versions as defined for this release of Grok.
Modified: grok/trunk/setup.py
===================================================================
--- grok/trunk/setup.py 2010-12-30 11:29:05 UTC (rev 119219)
+++ grok/trunk/setup.py 2010-12-30 12:02:25 UTC (rev 119220)
@@ -19,6 +19,13 @@
'zope.testing',
]
+docs_require = [
+ 'Sphinx',
+ 'collective.recipe.sphinxbuilder',
+ 'docutils',
+ 'roman',
+ ]
+
setup(
name='grok',
version='1.4dev',
@@ -91,5 +98,6 @@
'zope.traversing',
],
tests_require=tests_require,
- extras_require={'test': tests_require},
+ extras_require={'test': tests_require,
+ 'docs': docs_require},
)
Modified: grok/trunk/src/grok/components.py
===================================================================
--- grok/trunk/src/grok/components.py 2010-12-30 11:29:05 UTC (rev 119219)
+++ grok/trunk/src/grok/components.py 2010-12-30 12:02:25 UTC (rev 119220)
@@ -50,12 +50,13 @@
class Application(grokcore.site.Site):
"""Mixin for creating Grok application objects.
- When a `grok.Container` (or a `grok.Model`, though most developers
- use containers) also inherits from `grok.Application`, it not only
- gains the component registration abilities of a `grok.Site`, but
- will also be listed in the Grok admin control panel as one of the
- applications that the admin can install directly at the root of
- their Zope database.
+ When a :class:`grok.Container` (or a :class:`grok.Model`, though
+ most developers use containers) also inherits from
+ :class:`grok.Application`, it not only gains the component
+ registration abilities of a :class:`grok.Site`, but will also be
+ listed in the Grok admin control panel as one of the applications
+ that the admin can install directly at the root of their Zope
+ database.
"""
interface.implements(grokcore.site.interfaces.IApplication)
@@ -64,6 +65,9 @@
class View(grokcore.view.View):
"""The base class for views with templates in Grok applications.
+ Implements the :class:`grokcore.view.interfaces.IGrokView`
+ interface.
+
Each class that inherits from `grok.View` is designed to "render" a
category of content objects by reducing them to a document (often an
HTML document). Every view has a name, and is invoked when users
@@ -134,7 +138,10 @@
interface.implements(interfaces.IGrokView)
def application_url(self, name=None, data=None):
- """Return the URL of the nearest enclosing `grok.Application`."""
+ """Return the URL of the closest :class:`grok.Application` object in
+ the hierarchy or the URL of a named object (``name``
+ parameter) relative to the closest application object.
+ """
return util.application_url(self.request, self.context, name, data)
def flash(self, message, type='message'):
@@ -145,14 +152,15 @@
class Form(grokcore.formlib.Form, View):
"""The base class for forms in Grok applications.
- A class that inherits from `grok.Form` is a `grok.View` whose
- template will be given information about the fields in its context,
- and use that information to render an HTML form for adding or
- editing the form. Generally developers use one of the subclasses:
+ A class that inherits from :class:`grok.Form` is a
+ :class:`grok.View` whose template will be given information about
+ the fields in its context, and use that information to render an
+ HTML form for adding or editing the form. Generally developers
+ use one of the subclasses:
- * `grok.AddForm`
- * `grok.DisplayForm`
- * `grok.EditForm`
+ * :class:`grok.AddForm`
+ * :class:`grok.DisplayForm`
+ * :class:`grok.EditForm`
"""
interface.implements(interfaces.IGrokForm)
@@ -182,16 +190,18 @@
class IndexesClass(object):
"""Base class for index collections in a Grok application.
- A `grok.Indexes` utility provides one or more Zope Database content
- indexes for use in a `grok.Site` or `grok.Application`. The site or
- application that the indexes are intended for should be named with
- the `grok.site()` directive, and the kind of object to index should
- be named with a `grok.context()` directive.
+ A `grok.Indexes` utility provides one or more Zope Database
+ content indexes for use in a :class:`grok.Site` or
+ :class:`grok.Application`. The site or application that the
+ indexes are intended for should be named with the :func:`grok.site()`
+ directive, and the kind of object to index should be named with a
+ :func:`grok.context()` directive.
Inside their class, the developer should specify one or more
- `grok.index.Field` instances naming object attributes that should be
- indexed (and therefore searchable)::
-
+ :class:`grok.index.Field`, :class:`grok.index.Text`, or
+ :class:`grok.index.Set` instances naming object attributes that
+ should be indexed (and therefore searchable).::
+
class ArticleIndex(grok.Indexes):
grok.site(Newspaper)
grok.context(Article)
@@ -199,15 +209,18 @@
title = index.Field()
body = index.Text()
- See the `grok.index` module for more information on field types.
+ See the :mod:`grok.index` module for more information on field
+ types.
- Note that indexes are persistent: they are stored in the Zope
- database alongside the site or application that they index. They
- are created when the site or application is first created, and so an
- already-created site will not change just because the definition of
- one of its `grok.Indexes` changes; it will either have to be deleted
- and re-created, or some other operation performed to bring its
- indexes up to date.
+ .. note:: Indexes are persistent: they are stored in the Zope
+ database alongside the site or application that they
+ index. They are created when the site or application is
+ first created (and made persistent), and so an
+ already-created site will not change just because the
+ definition of one of its :data:`grok.Indexes` changes;
+ it will either have to be deleted and re-created, or
+ some other operation performed to bring its indexes up
+ to date.
"""
def __init__(self, name, bases=(), attrs=None):
Modified: grok/trunk/src/grok/index.py
===================================================================
--- grok/trunk/src/grok/index.py 2010-12-30 11:29:05 UTC (rev 119219)
+++ grok/trunk/src/grok/index.py 2010-12-30 12:02:25 UTC (rev 119220)
@@ -29,24 +29,27 @@
class IndexDefinition(object):
- """The definition of a particular index in a `grok.Indexes` class.
+ """The definition of a particular index in a :data:`grok.Indexes`
+ class.
- This base class defines the actual behavior of `grok.index.Field`
- and the other kinds of attribute index that Grok supports. Upon our
- instantiation, we save every parameter that we were passed; later,
- if an index actually needs to be created (which is typically at the
- moment when a new `grok.Application` object is added to the Zope
- Database), then our `setup()` method gets called.
+ This base class defines the actual behavior of
+ :class:`grok.index.Field` and the other kinds of attribute index
+ that Grok supports. Upon our instantiation, we save every
+ parameter that we were passed; later, if an index actually needs
+ to be created (which is typically at the moment when a new
+ :class:`grok.Application` object is added to the Zope Database),
+ then our :meth:`setup()` method gets called.
The only parameter that is actually significant to us is `attribute`
which (optionally) defines the attribute we should index. All other
parameters are simply passed along to the Zope index we create,
which interprets them as configuration details of its own.
- Note that, since index creation (and thus a call to our `setup()`
- method) currently occurs only during the creation of a new Grok
- `Application` object in the Zope Database, the presence of this
- declaration in Grok application code is nearly always a no-op.
+ Note that, since index creation (and thus a call to our
+ :meth:`setup()` method) currently occurs only during the creation
+ of a new Grok `Application` object in the Zope Database, the
+ presence of this declaration in Grok application code is nearly
+ always a no-op.
"""
implements(IIndexDefinition)
@@ -91,15 +94,16 @@
class Field(IndexDefinition):
- """A `grok.Indexes` index that matches against an entire field."""
+ """A :class:`grok.Indexes` index that matches against an entire field."""
index_class = FieldIndex
class Text(IndexDefinition):
- """A `grok.Indexes` index supporting full-text searches of a field."""
+ """A :class:`grok.Indexes` index supporting full-text searches of a
+ field."""
index_class = TextIndex
class Set(IndexDefinition):
- """A `grok.Indexes` index supporting keyword searches of a field."""
+ """A :class:`grok.Indexes` index supporting keyword searches of a field."""
index_class = SetIndex
Modified: grok/trunk/src/grok/testing.py
===================================================================
--- grok/trunk/src/grok/testing.py 2010-12-30 11:29:05 UTC (rev 119219)
+++ grok/trunk/src/grok/testing.py 2010-12-30 12:02:25 UTC (rev 119220)
@@ -11,7 +11,7 @@
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
-"""Grok test helpers
+"""Grok test helpers.
"""
import sys
from zope.configuration.config import ConfigurationMachine
@@ -21,6 +21,15 @@
def grok(module_name):
+ """Grok a module.
+
+ Test helper to 'grok' a module named by `module_name`, a dotted
+ path to a module like ``'mypkg.mymodule'``. 'grokking' hereby
+ means to do all the ZCML configurations triggered by directives
+ like ``grok.context()`` etc. This is only needed if your module
+ was not `grokked` during test setup time as it normally happens
+ with functional tests.
+ """
config = ConfigurationMachine()
zcml.do_grok('grokcore.component.meta', config)
zcml.do_grok('grokcore.security.meta', config)
@@ -44,7 +53,7 @@
Modified copy from zope.deprecation.tests to:
* make the signature identical to warnings.warn
- * to check for *.pyc and *.pyo files.
+ * to check for \*.pyc and \*.pyo files.
When zope.deprecation is fixed, this warn function can be removed again.
"""
More information about the checkins
mailing list