[Checkins]
SVN: Sandbox/ulif/grok-adminui/src/grok/admin/docgrok.txt
Improved docgrok docs/tests.
Uli Fouquet
uli at gnufix.de
Mon Jul 16 15:00:18 EDT 2007
Log message for revision 78038:
Improved docgrok docs/tests.
Changed:
U Sandbox/ulif/grok-adminui/src/grok/admin/docgrok.txt
-=-
Modified: Sandbox/ulif/grok-adminui/src/grok/admin/docgrok.txt
===================================================================
--- Sandbox/ulif/grok-adminui/src/grok/admin/docgrok.txt 2007-07-16 18:07:32 UTC (rev 78037)
+++ Sandbox/ulif/grok-adminui/src/grok/admin/docgrok.txt 2007-07-16 19:00:17 UTC (rev 78038)
@@ -167,9 +167,101 @@
Writing new DocGroks
++++++++++++++++++++
-XXX: to be written.
+Consider we want to document ``grok.View`` classes. Since
+``grok.View`` is a class, we choose the DocGrokClass as base for our
+new DocGrok:
+ >>> from grok.admin.docgrok import DocGrokClass
+ >>> class DocGrokGrokView(DocGrokClass):
+ ... """"This doctor cares for grok.Views."""
+ ... pass
+
+Now we create a doctor:
+
+ >>> doctor = DocGrokGrokView()
+ Traceback (most recent call last):
+ [...]
+ TypeError: __init__() takes exactly 2 arguments (1 given)
+
+Oops! Well, we didn't specify, what kind of DocGrokView we want to
+examine. We can do that, giving a dotted name:
+
+ >>> doctor = DocGrokGrokView('grok.View')
+ >>> doctor
+ <DocGrokGrokView ...>
+
+The doctor is in. Fine. So let's see, what he can tell us about
+``grok.View``.
+
+ >>> doctor.getPath()
+ 'grok.View'
+
+Ah, yes, very interesting. We got the dotted path of the examined
+class. But, where can we find the definition of it in file system? Ask
+the doc:
+
+ >>> doctor.getFilePath()
+ '.../grok/__init__.py'
+
+This is not exactly, what we wanted to know, is it? We got the package
+location instead of the module. So the path is wrong. Really? When you
+have a look at the specified ``__init__.py``, you will discover, that
+there is indeed an assignment, which says, that ``grok.View`` is
+another name for ``grok.components.View``. It is simply a shortcut. So,
+as we asked for ``grok.View`` the answer was correct.
+
+To check it, let's see, what happens, if we give the real dotted path:
+
+ >>> doctor = DocGrokGrokView('grok.components.View')
+ >>> doctor.getFilePath()
+ '.../grok/components.py'
+
+Ah, right. This is, what we wanted. Now we can use some of the derived
+methods to gather some more information about this class:
+
+ >>> methods = doctor.getMethods()
+
+delivers us a list of all public methods defined in this class. Each
+list entry being a dictionary with keys ``name``, ``signature``,
+``doc``, ``interface``, ``attr``, ``read_perm`` and `` write_perm``.
+
+ >>> entry = [x for x in methods if x['name'] == 'url'][0]
+ >>> entry['name']
+ 'url'
+ >>> entry['doc']
+ ''
+ >>> entry['signature']
+ '(obj=None, name=None)'
+
+The other methods work as described in the ``DocGrokClass``
+documentation.
+
+This is all very well, but not too impressive. We could gather the
+information delivered relatively easy writing some simple
+snippets. So, what is it all about?
+
+One main reason is, that ``DocGroks`` are used by the Grok admin
+interface to provide easy accessible API documentation. Those
+documentation is basically able, to give some information about
+everything, which is describable as a dotted path. But some of the
+information is not very descriptive. That's it, why ``docgrok`` uses a
+set of helpers, to give more detailed information. If you, for
+instance, want that instead of the standard class-related docgrok your
+own docgrok is displayed, whenever a user wants to know something
+about ``grok.View`` and related classes, then you can register your
+docgrok and let it display documentation for ``grok.View``.
+
+The selection to register a docgrok for ``grok.View`` was very
+arbitrary. You can also register a docgrok, that handles all elements,
+whose name starts with the letter 'a' or those elements, which are
+classes and implement at least three different interfaces. It's
+completely up to you.
+
+To choose, which API elements your docgrok is able to handle, you have
+to define a handler function. This is what we want to do next.
+
+
Create a handler
++++++++++++++++
More information about the Checkins
mailing list