[Grok-dev] Re: admin ui: displaying application docstrings

[Martijn Faassen]

Hey,

> How about a 'grok.describe' directive used for UI:
>
>   class FooClass(grok.Application):
>       """ Foo
>
>       This comment not for users.
>       """
>       grok.describe(title='Foo Application',
>                     description='User-friendly Foo')

That's a good idea. We could also have it split into two:

grok.title('Foo Application') # could be grok.label?
grok.description('User-friendly Foo')

> A variant might be to pass a single string, using docstring conventions,
> and parse it.  Packages which didn't need to distinguish between UI and
> developer docs could then call:
>
>       grok.describe(docstring=__doc__)

Interesting idea, but I think we shouldn't depend on docstring
conventions with our main API. If this is something people end up
doing often we could provide them with some utility function.

> > That said, we cannot make changes now, we need to think about this
> > some more. For the time being, let's stick with the dotted name and
> > the first line of the docstring. I just think that this is something
> > we may end up reconsidering as we consider the audience for this
> > screen further.
>
> The audience for that screen is not as broad as it might seem:  it is
> "site managers", rather than "all users".

True. Still a different audience than developers, though generally
more accepting of techy stuff than end users.

Regards,

Martijn