[Grok-dev] Re: admin ui: displaying application docstrings
tseaver at palladion.com
Mon Aug 20 10:55:10 EDT 2007
-----BEGIN PGP SIGNED MESSAGE-----
Martijn Faassen wrote:
>> 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:
This comment not for users.
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:
> 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 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
-----END PGP SIGNATURE-----
More information about the Grok-dev