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

[Tres Seaver]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Martijn Faassen wrote:
> Hey,
> 
>> Uli has a point. We can now change the tutorial and explain that the
>> docstring of grok.Application subclasses will appear in the admin UI.
>> Just because we didn't think of it when we wrote grokwiki doesn't mean
>> it's not a good idea :). I think docstrings are actually a very neat way
>> of getting some explanatory text into the UI.
> 
> I'm just worried about the dual purpose of docstring - code
> documentation and something that shows up in the UI.
> 
> Now of course it makes sense to show docstrings when looking through
> the documentation section of the admin UI. But the application
> installation section is something that many others besides developers
> will be confronted with, and we should consider what its goals are. Is
> this for users and developers both, or for developers only?
> 
> If it's for users and developers both, I think we should consider not
> using the dotted name for the applications anymore either, and not use
> the docstring. This because two different demands will be made on the
> docstring otherwise: UI and code documentation, and those often pull
> in different ways. We should consider supporting menu registration,
> where an application can say "I have this name, and this describes
> what I do for UI purposes".

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')

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__)

> 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".


Tres.
- --
===================================================================
Tres Seaver          +1 540-429-0999          tseaver at palladion.com
Palladion Software   "Excellence by Design"    http://palladion.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFGyatO+gerLs4ltQ4RAha4AKCHW6pNfZq7WUVBMoBT23C3C14n2QCgzWzr
tmsExJldryUfGrZA4+DJtto=
=jjVZ
-----END PGP SIGNATURE-----