[Zope3-checkins] CVS: Zope3/doc/zcml - meta.stx:1.5
R. David Murray
bitz@bitdance.com
Wed, 6 Nov 2002 17:15:38 -0500
Update of /cvs-repository/Zope3/doc/zcml
In directory cvs.zope.org:/tmp/cvs-serv8509
Modified Files:
meta.stx
Log Message:
Merge the rdmurray-metameta-branch.
This brings in a number of changes to the configuration system. The
update to doc/zcml/meta.zcml documents the "new way" of doing
meta-configuration. The old way still works fine, and the only
meta.zcml file I've changed to the new way (so far) is the one
for the content directive.
This update introduces a new utility, makezcmldocs.py. It is best
run under python2.3, because under 2.2 it uses a fake TextWrap class
that is very stupid about wrapping. If you run makezcmldocs.py
it will extract any existing documentation from the metaconfiguration
directives in the system and write out structured text files in a
directory named 'doc/zcml.new/namespaces.zope.org'. (Eventually
this will be changed so that it replaces the existing
doc/zcml/namespaces.zope.org). It also spits out error messages
for any directives that don't have description attributes. If yours
are among them, please consider fixing them <grin>.
One other change introduced by this update that it is important
to be aware of is that INonEmptyDirectives *must* now declare
that they implement INonEmptyDirective or they will not function
correctly. (Previous to this update they would work as long
as at least one subdirective was actually defined). All of
the existing directives are updated in this checkin.
Also, note that if you do fix your meta.zcml files, and your unit
tests actually test your meta.zcml file, you will need to update
your unit test to call XMLConfig('metameta.zcml',Zope.Configuration)()
before reading your own meta.zcml file. This update is done for
the content directive in this checkin.
=== Zope3/doc/zcml/meta.stx 1.4 => 1.5 ===
--- Zope3/doc/zcml/meta.stx:1.4 Thu Sep 19 14:50:12 2002
+++ Zope3/doc/zcml/meta.stx Wed Nov 6 17:15:37 2002
@@ -1,29 +1,61 @@
The Meta Configuration System
Meta configuration is the configuration of the configuration
- system. In the case of zcml, this means using the "bootstrap"
+ system. In the case of zcml, this means using the "metaconfiguration"
zcml configuration directives to define the configuration directives
that will actually be used to configure the system.
The Meta Configuration Directives
- The "bootstrap" directives are 'directives', 'directive', and
+ The metaconfiguration directives are 'directives', 'directive', and
'subdirective'. We'll use a shortened version of the
meta-configuration for the Zope StartUp system to explain the
- concepts::
+ concepts (note that this may not bear any real relationship
+ to the actual StartUp system configuration)::
<ZopeConfigure xmlns="http://namespaces.zope.org/zope">
<directives namespace="http://namespaces.zope.org/startup">
<directive
name="registerRequestFactory"
- attributes="name publication request"
- handler="Zope.StartUp.metaConfigure.registerRequestFactory" />
+ handler="Zope.StartUp.metaConfigure.registerRequestFactory"
+ description="Register a factory component that will produce
+ request objects when requested by the publisher."
+ >
+ <attribute
+ name="name"
+ description="the name used to refer to this factory" />
+ <attribute
+ name="publication"
+ description="resolvable name of the publication component" />
+ <attribute
+ name="request"
+ required="yes"
+ description="resolvable name of the component that implements
+ the factory" />
+ </directive>
<directive
name="defineSite"
- attributes="name threads"
handler="Zope.Startup.metaConfigure.defineSite">
- <subdirective name="useFileStorage" attributes="file" />
- <subdirective name="useMappingStorage" />
+ description="Declare a particular server instance"
+ >
+ <attribute
+ name="name"
+ description="text label that identifies the server" />
+ <attribute
+ name="threads"
+ description="the number of threads that will be used to service
+ requests to this server" />
+ <subdirective
+ name="useFileStorage"
+ description="Indicate this server should use a FileStorage" />
+ >
+ <attribute
+ name="file"
+ description="the name of the file to use for the FileStorage" />
+ </subdirective>
+ <subdirective
+ name="useMappingStorage"
+ description="Indicate that this server should use a MappingStorage" />
</directive>
</directives>
</ZopeConfigure>
@@ -41,9 +73,15 @@
The first example directive directive defines a directive that
has no subdirectives. The 'name' attribute gives the name of
the directive. So in this case we are defining the
- 'registerRequestFactory' directive. Combining the namespace
- with this name, this means we are defining a directive that
- would look something like this when used::
+ 'registerRequestFactory' directive.
+
+ The 'description' attribute allows us to provide explanatory
+ text about the directive. This text will be extracted by tools
+ for display to users of the configuration system. By convention
+ this text may use any in-line StructuredText markup.
+
+ Combining the namespace with the name, we are defining a directive
+ that would look something like this when used::
<ZopeConfigure
xmlns="http://namespaces.zope.org/zope"
@@ -52,14 +90,27 @@
<startup:registerRequestFactory ....>
</ZopeConfigure>
- The "attributes" attribute of the directive directive allows
- us to fill in the "...." in the example above. It lists the
- names of the attributes that will be valid for this directive.
- So this meta-configuration is saying that the registerRequestFactory
- directive can have attributes named 'name', 'publication', or
- 'request'.
+ Inside the directive directive we have 'attribute' subdirectives.
+ These allow us to name and describe the allowed attributes
+ of the directive we are defining. This allows us to fill in
+ the "..." in the example above: the various attribute subdirectives
+ let us know that the registerRequestFactory directive can have
+ attributes named 'name', 'publication', or 'request'. It also
+ tells us that 'publication' is optional, and describes what the
+ attributes are for. (Of course, in real code the descriptions
+ would be more meaningful).
+
+ The valid values for 'required' are 'yes' and 'no'. Yes means
+ the attribute must be present or an error will be raised (this
+ is done by the python code that implements the directive).
+ A value of 'no' means that the attribute can always be omitted.
+ If this attribute is not specified when configuring a directive,
+ then either the attribute is optional or it may be part of a
+ set of attributes one of which must be specified. However,
+ all this is a documentation convention; how the directive
+ actually works is determined by the python code that implements it.
- The directive we are defining can thus look something like this
+ So, the directive we are defining can look something like this
when used::
<ZopeConfigure
@@ -72,9 +123,6 @@
request="Zope.Publisher.VFS.VFSRequest." />
</ZopeConfigure>
- Which attributes are optional and which are required is controlled
- by the python code that implements the directive.
-
The 'handler' attribute is what defines which python code will
handle the directive. It must be a resolvable name following
the standard zcml rules.
@@ -308,3 +356,15 @@
in an included file specifies a thread count, it will get
overridden by a site definition in an upper level file because
of the discriminator conflict resolution.
+
+ Overriding Directive Definitions
+
+ Although it is not something that is useful in most normal
+ projects, it is possible to override the definition of a
+ directive. Unlike with configuration actions, where directives
+ in included files are overridden by directives in the including
+ files, metaconfiguration directives take effect as soon as they
+ are encountered. When you re-specify the definition of a directive,
+ you affect only the attributes of that directive. Any defined
+ attributes or subdirectives remain defined unless they, too,
+ are overridden. Currently it is not possible to delete a directive.