The zcml namespace is not in the apidoc

[tseaver]

In https://bugs.launchpad.net/zope.configuration/+bug/135267, Christian Zagrodnick reported:

ZCML directives like zcml:condition form the http://namespaces.zope.org/zcml namespace are not in the apidoc's ZCML reference.

@philikon replied:

zcml:condition is not a directive, it's an inherent feature of the configuration machinery.

@freddrake followed up:

It still needs to be documented in an accessible location.

@miohtama replied:

The only reference documentation for zcml:condition is this bug report.

I'd like to really find any documentation/source for zcml:condition.

  <adapter  zcml:condition="installed ore.contentmirror"
   ...>

@philikon:

That doesn't mean this is the right place to ask for more documentation. I recommend writing to the mailto:zope@zope.org or zope3-users@zope.org list.

My book (http://worldcookery.com) mentions it in Chapter 13 and the ZCML reference (Appendix B).

@benji-york:

Also see http://svn.zope.org/*checkout*/zope.configuration/trunk/src/zope/configuration/tests/test_conditions.py?content-type=text%2Fplain

@miohtama:

Even though this might not be a right place to ask help, I consider it's a bug if the API is not well enough documented. It's just to balancing the sentence structure between "this thing is not properly documented" and "how I work with this because I cannot find any documents."

This page has some data:

http://wiki.zope.org/zope3/ZcmlConditionFeatures

But it fails to mention e.g. has condition "installed zope.app.catalog" like used in here:

https://textindexng.svn.sourceforge.net/svnroot/textindexng/textindexng/trunk/src/textindexng/configure.zcml

ZcmConditionFeatures page lacks completely examples.

Zope API documents at http://apidoc.zope.org/++apidoc++/ don't mention how to use zcml: directives. The reason is explained in this document chain, but is is just an obstacle. How it could be possible to generate API documentation for ZCML inhereted features?

I was going to create some examples in Zope 3 wiki, but I couldn't find any source material, so I started bragging here.

[jamadden]

There is some documentation of zcml:condition in docs/narr.rst (https://zopeconfiguration.readthedocs.io/en/stable/narr.html#making-specific-directives-conditional), but it is very incomplete. It is structured as a series of doctests, and doesn't actually show the ZCML that's executed, so it's quite hard to follow. Crucially, it also only documents have, leaving out installed and the not- variants of each.

The API documentation for ConfigurationHandler is somewhat better in that it demonstrates all the conditions. But that doesn't tie it back to the XML syntax.