[Checkins] SVN: grok/branches/neanderthal-reference-documentation/doc/reference/functions.rst moved grok.grok function from core.rst to this file

[Luciano Ramalho]

Log message for revision 80496:
  moved grok.grok function from core.rst to this file
  

Changed:
  U   grok/branches/neanderthal-reference-documentation/doc/reference/functions.rst

-=-
Modified: grok/branches/neanderthal-reference-documentation/doc/reference/functions.rst
===================================================================
--- grok/branches/neanderthal-reference-documentation/doc/reference/functions.rst	2007-10-02 14:50:33 UTC (rev 80495)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/functions.rst	2007-10-02 14:50:47 UTC (rev 80496)
@@ -86,7 +86,7 @@
       :func:`grok.AutoFields`, :class:`grok.Form`
 
 :func:`grok.getSite`
-====================
+===============================================
 
 
 .. function:: grok.getSite()
@@ -157,3 +157,44 @@
       View classes derived from :class:`grok.View` have a similar :meth:`url` method
       for constructing URLs.
 
+
+:func:`grok.grok` -- Grok a package or module
+=============================================
+
+
+.. function:: grok(dotted_name)
+
+.. note:: Usually you don't need to invoke this funtion in your code, since it's triggered from the `configure.zcml`. Grokking test fixtures is one  situation where it is useful to call this explicitly.
+
+Grokking a package or module activates the contained components (like models,
+views, adapters, templates, etc.) and registers them with Zope 3's component
+architecture.
+
+The `dotted_name` must specify either a Python module or package that is
+available from the current PYTHONPATH.
+
+Grokking a module:
+
+#. Scan the module for known components: models, adapters, utilities, views,
+      traversers, templates and subscribers.
+
+#. Check whether a directory with file system templates exists
+(:file:`<modulename>_templates`). If it exists, load the file system templates
+into the template registry for this module.
+
+#. Determine the module context.
+
+#. Register all components with the Zope 3 component architecture.
+
+#. Initialize schemata for registered models
+
+   Grokking a package:
+
+#. Grok the package as a module.
+
+#. Check for a static resource directory (:file:`static`) and register it if
+it exists.
+
+#. Recursively grok all sub-modules and sub-packages.
+
+