[Checkins] SVN: grok/branches/ulif-docs2sphinx/doc/reference/components.rst Start deploying sphinx autodoc.
Uli Fouquet
uli at gnufix.de
Sun Dec 26 11:14:35 EST 2010
Log message for revision 119140:
Start deploying sphinx autodoc.
Changed:
U grok/branches/ulif-docs2sphinx/doc/reference/components.rst
-=-
Modified: grok/branches/ulif-docs2sphinx/doc/reference/components.rst
===================================================================
--- grok/branches/ulif-docs2sphinx/doc/reference/components.rst 2010-12-26 16:14:09 UTC (rev 119139)
+++ grok/branches/ulif-docs2sphinx/doc/reference/components.rst 2010-12-26 16:14:34 UTC (rev 119140)
@@ -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
@@ -413,8 +390,11 @@
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".
@@ -457,6 +437,7 @@
:func:`grok.provides`
+
**Example 1: Simple adaptation example**
.. code-block:: python
@@ -514,11 +495,12 @@
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.
@@ -535,13 +517,13 @@
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.
+ 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 +556,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 +575,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,7 +630,8 @@
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".
@@ -665,9 +649,9 @@
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.
+ 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,11 +667,12 @@
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:**
@@ -698,19 +683,21 @@
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.
+ 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 +710,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 +750,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 +800,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 +827,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 +838,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 +865,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 +951,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 +970,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 +1008,24 @@
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
+ :members:
+ :inherited-members:
+ :undoc-members:
- Base class for JSON methods.
+ .. attribute:: context
+
+ Object that the REST handler presents.
+ .. attribute:: request
+
+ Request that REST handler was looked up with.
+
+ .. attribute:: body
+
+ The text of the request body.
+
+
**Example 1: Create a public and a protected JSON view.**
.. code-block:: python
@@ -1010,10 +1055,11 @@
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
+ :members:
+ :inherited-members:
+ :undoc-members:
- Base class for REST.
-
.. attribute:: context
Object that the REST handler presents.
@@ -1022,20 +1068,51 @@
Request that REST handler was looked up with.
- .. attribute:: body
+ .. autoattribute:: grok.REST.response
+
+ The response sent back to the client.
+
+ .. autoattribute:: grok.REST.body
The text of the request body.
+ .. automethod:: grok.REST.application_url
+ .. automethod:: grok.REST.url
+
+ .. automethod:: grok.REST.redirect
+
+
: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 +1139,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 +1152,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:: grok.Traverser.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:: grok.Traverser.browserDefault
+
Returns an object and a sequence of names.
The publisher calls this method at the end of each traversal path.
@@ -1090,24 +1167,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:: grok.Traverser.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 +1220,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,17 +1248,26 @@
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
~~~~~
More information about the checkins
mailing list