ZCML Documentation (was Re: [Zope3-dev] ZCML alternative)

[Jim Fulton]

"Phillip J. Eby" wrote:
> 
...

> But there is one interesting idea that comes to mind from it, regarding
> ease of understanding ZCML...
> 
> Suppose that ZCML namespace URLs were required (by convention) to be
> documentation for the contents of that namespace?
> 
> That is, http://namespaces.zope.org/security/ would be a page on the
> security namespace, with pages for the various directives contained
> therein.  This could be done as easily by third-party component creators as
> for Zope core components.  And in the case of core components, there could
> be a place in the Zope 3 distribution that corresponded to the
> http://namespaces.zope.org/ tree, so that the docs are locally available,
> and so that Zope developers could update the docs when they're updating the
> directives.

This is a fine idea. I'm not going to sign up for setting up namespaces.zope.org
soon, but that would be a good idea in the long term. In the mean time, we could
provide the directive documentation somewhere locally along these lines.

Anybody want to suggest a specific location?
 
> With an appropriate documentation format, one could even define a unit test
> that cross-checked the source ZCML files against the docs to ensure that no
> undocumented directives or attributes thereof were being used, so that
> failing to document a new directive or updated syntax would "break the
> build".  :)

I'm leaning toward replacing the current ZCML meta-directive mechanism
with something based on XML Schema. Then you could use schema validators
to validate the configuration files.

> Maybe that is going a little far, but I do agree with Shane that
> understanding ZCML right now is *hard*.  If we're solidifying ZCML, perhaps
> it's time to solidify a location for its documentation...  Given that the
> namespace URL's have to be in the ZCML for it to work, they seem like a
> good place.

A starting point is to write some documentation for ZCML. :)

I'm open to suggestions on where to put it too.

Jim

--
Jim Fulton           mailto:jim@zope.com       Python Powered!        
CTO                  (888) 344-4332            http://www.python.org  
Zope Corporation     http://www.zope.com       http://www.zope.org