3 in 1

Since automated tests rule a part of state-of-the-art software development and XML is widespread used to serialize data in some way, i combined the API documentation and the doctest as well as the XML outcome and usage for XML processing libraries. Here's a result of this thougts as testcase for a custom ZCML directive.

<!--
  Test metaconfigure. This file is both a zcml config and a doctest.
  
  Test here if model profiles are instanciated as expected.
-->
<configure xmlns="http://namespaces.zope.org/devilstickmodel">

  <!--
    When defining profiles, the order of directives is important to make sure
    the element where you want to insert other elements is already
    available.
    
    A profile itself is simply registered by its name.
  -->
  <profile name="testprofile" />

  <!--
    Load test profile...

      >>> from zope.configuration.xmlconfig import XMLConfig
      >>> import devilstick.model
    
    Keep config, need its context later
    
      >>> config = XMLConfig('metaconfigure.txt', devilstick.model)
      >>> config()
    
    ...and query it

      >>> from zope.component import getUtility
      >>> from devilstick.interfaces import IProfile
      >>> profile = getUtility(IProfile, name='testprofile')
      >>> profile
      <devilstick.model.model.ComplexElement object at ...>

...and so on.

This is a simple doctest which is valid XML, where comments contain the doctest code and the XML code demonstrates how all this stuff looks in the end.

The doctest is invoked as usual and uses itself as XML source the library has to be tested with.