[Checkins] SVN: grok/branches/ulif-docs2sphinx/src/grok/ Update various docstrings.
Uli Fouquet
uli at gnufix.de
Sun Dec 26 11:14:09 EST 2010
Log message for revision 119139:
Update various docstrings.
Changed:
U grok/branches/ulif-docs2sphinx/src/grok/components.py
U grok/branches/ulif-docs2sphinx/src/grok/index.py
-=-
Modified: grok/branches/ulif-docs2sphinx/src/grok/components.py
===================================================================
--- grok/branches/ulif-docs2sphinx/src/grok/components.py 2010-12-26 16:13:19 UTC (rev 119138)
+++ grok/branches/ulif-docs2sphinx/src/grok/components.py 2010-12-26 16:14:09 UTC (rev 119139)
@@ -48,12 +48,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)
@@ -62,6 +63,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
@@ -132,7 +136,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'):
@@ -308,16 +315,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)
@@ -325,15 +334,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/branches/ulif-docs2sphinx/src/grok/index.py
===================================================================
--- grok/branches/ulif-docs2sphinx/src/grok/index.py 2010-12-26 16:13:19 UTC (rev 119138)
+++ grok/branches/ulif-docs2sphinx/src/grok/index.py 2010-12-26 16:14:09 UTC (rev 119139)
@@ -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
More information about the checkins
mailing list