[Zope3-checkins] CVS: Zope3/src/zope/products/apidoc/servicemodule - __init__.py:1.1 browser.py:1.1 configure.zcml:1.1 index.pt:1.1 menu.pt:1.1 tests.py:1.1

[Stephan Richter]

Update of /cvs-repository/Zope3/src/zope/products/apidoc/servicemodule
In directory cvs.zope.org:/tmp/cvs-serv11915/apidoc/servicemodule

Added Files:
	__init__.py browser.py configure.zcml index.pt menu.pt 
	tests.py 
Log Message:
Here comes the new Zope 3 API Documentation tool. You can access it via

  http://localhost:8080/++apidoc++/

There is really not much more to say here. Check it out and let me know what
you think.


=== Added File Zope3/src/zope/products/apidoc/servicemodule/__init__.py ===
##############################################################################
#
# Copyright (c) 2004 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.0 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""Service Documentation Module

$Id: __init__.py,v 1.1 2004/01/29 17:51:17 srichter Exp $
"""
from zope.app import zapi
from zope.interface import implements
from zope.products.apidoc.interfaces import IDocumentationModule
from zope.products.apidoc.utilities import ReadContainerBase
from zope.app.interfaces.location import ILocation
from zope.component import ComponentLookupError

class Service(object):
    """Object representing a service in the API documentation"""

    implements(ILocation)

    def __init__(self, parent, name, iface, impl):
        self.__parent__ = parent
        self.__name__ = name
        self.interface = iface
        self.implementations = impl


class ServiceModule(ReadContainerBase):
    r"""Represent the Documentation of all Interfaces.

    This documentation is implemented using a simply 'IReadContainer'. The
    items of the container are all the interfaces listed in the closest
    interface service and above.

    Demonstration::

      >>> from zope.app.tests import placelesssetup as setup
      >>> setup.setUp()

      >>> module = ServiceModule()

      >>> module.get('Interfaces').__name__
      'Interfaces'

      >>> module.get('foo') is None
      True
      
      >>> print '\n'.join([id for id, iface in module.items()][:4])
      Adapters
      EventPublication
      Factories
      Interfaces
      
      >>> setup.tearDown()
    """

    implements(IDocumentationModule)

    # See zope.products.apidoc.interfaces.IDocumentationModule
    title = 'Services'

    # See zope.products.apidoc.interfaces.IDocumentationModule
    description = """
    The services module let's the reader browse through all defined
    services. It uses the service name as a key. In general services can be
    queried using::

      >>> from zope.app import zapi
      >>> service = zapi.getService(None, 'ServiceName')

    Here we used 'None' as the location, which means that always a global
    service is returned. If you use an object that has a location in the
    traversal tree, you will generally get the closest service, which includes
    the local ones. The second argument is the service name, which you can
    replace with any name listed in this module's menu.

    For each service, the attributes and methods of the service interface are
    presented. At the end a list of implementations is given.
    """

    def get(self, key, default=None):
        """See zope.app.interfaces.container.IReadContainer"""
        service = zapi.getService(self, 'Services')        
        items = service.getServiceDefinitions()
        for name, iface in items:
            if name == key:
                try:
                    impl = service.getService(name)
                except ComponentLookupError:
                    impl = None
                return Service(self, name, iface, [impl])

        return default

    def items(self):
        """See zope.app.interfaces.container.IReadContainer"""
        service = zapi.getService(self, 'Services')
        items = service.getServiceDefinitions()
        items.sort()
        return [(name, self.get(name)) for name, iface in items]


=== Added File Zope3/src/zope/products/apidoc/servicemodule/browser.py ===
##############################################################################
#
# Copyright (c) 2004 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.0 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""Service Details View

$Id: browser.py,v 1.1 2004/01/29 17:51:17 srichter Exp $
"""
from zope.app import zapi
from zope.app.location import LocationProxy
from zope.interface.declarations import providedBy
from zope.products.apidoc.ifacemodule.browser import InterfaceDetails
from zope.products.apidoc.utilities import getPythonPath
from zope.proxy import removeAllProxies
from zope.schema.interfaces import IField


class Menu(object):
    """Menu View Helper Class"""

    def getMenuTitle(self, node):
        """Return the title of the node that is displayed in the menu."""
        return zapi.name(node.context)

    def getMenuLink(self, node):
        """Return the HTML link of the node that is displayed in the menu."""
        return './'+ zapi.name(node.context) + '/index.html'


class ServiceDetails(object):
    """View for a Service in the API Documentation"""

    def interface(self):
        """Get the details view of the interface the service provides."""
        iface = LocationProxy(self.context.interface,
                               self.context,
                               getPythonPath(self.context.interface))
        return InterfaceDetails(iface, self.request)
    
    def implementations(self):
        """Retrieve a list of implementations of this service."""
        impl = map(removeAllProxies, self.context.implementations)
        impl = map(lambda x: x.__class__, self.context.implementations)
        return map(getPythonPath, impl)


=== Added File Zope3/src/zope/products/apidoc/servicemodule/configure.zcml ===
<configure
  xmlns="http://namespaces.zope.org/zope"
  xmlns:browser="http://namespaces.zope.org/browser">

  <class class=".ServiceModule">
    <allow interface="zope.products.apidoc.interfaces.IDocumentationModule" />
    <allow interface="zope.app.interfaces.container.IReadContainer" />
  </class>

  <class class=".Service">
    <allow attributes="name interface implementations" />
  </class>

  <utility
    provides="zope.products.apidoc.interfaces.IDocumentationModule"
    factory=".ServiceModule"
    name="Service" />

  <browser:page
    for=".ServiceModule"
    permission="zope.View"
    class=".browser.Menu"
    name="menu.html"
    template="menu.pt" />

  <browser:page
    for=".Service"
    permission="zope.View"
    class=".browser.ServiceDetails"
    name="index.html"
    template="index.pt" />

</configure>


=== Added File Zope3/src/zope/products/apidoc/servicemodule/index.pt ===
<html metal:use-macro="views/apidoc_macros/details">
<body metal:fill-slot="contents"
      tal:define="iface view/interface">

  <h1 class="details-header"
      tal:content="string:${context/zope:name} Service"> 
    SampleService
  </h1>

  <div class="indent">
    <div class="documentation" tal:content="structure iface/getDoc">
      Here is the doc string
    </div>
  </div>

  <div class="indent">
    <h3>Interface: 
      <a href=""
         tal:attributes="href 
             string:../../Interface/${iface/getId}/apiindex.html"
         tal:content="iface/getId">zope.fields.Iface
      </a>
    </h3>
  </div>

  <h2 class="details-section">Attributes/Fields</h2>

  <div class="indent"
      tal:define="attributes iface/getAttributes;
                  fields iface/getFields">

  <ul class="attr-list" 
      tal:condition="python: attributes or fields">
  
    <li tal:repeat="attr attributes">
      <b><code tal:content="attr/name">attr</code></b> (Attribute)<br>
      <div class="inline-documentation" tal:content="structure attr/doc">
        attr desc
      </div>      
    </li>

    <li tal:repeat="field fields">
      <b><code tal:content="field/name">field</code></b>
      - <a href=""
           tal:attributes="href string:../${field/iface/id}/apiindex.html">
          <code tal:content="field/iface/name">IField</code></a>
      (<span tal:content="string:${field/required}, ">optional, </span>
        default = <code tal:content="field/default" />)<br>
      <span tal:content="field/description">field desc</span>      
    </li>

  </ul>

  <p tal:condition="python: not (attributes or fields)">
    <em>There are no attributes or fields specified.</em>
  </p>

  </div>



  <h2 class="details-section">Methods</h2>

  <div class="indent"
       tal:define="methods iface/getMethods">

  <ul class="attr-list" tal:condition="methods">
    <li tal:repeat="method methods">
      <b><code 
          tal:content="string:${method/name}${method/signature}" />
      </b><br>
      <div class="inline-documentation" tal:content="structure method/doc">
        method desc
      </div>      
    </li>
  </ul>

  <p tal:condition="not: methods">
    <em>There are no methods or fields specified.</em>
  </p>

  </div>


  
  <h2 class="details-section">Implementations</h2>
  <div class="indent">
    <ul>
      <li tal:repeat="impl view/implementations">
        <code><a href=""
           tal:attributes="href string:../../Class/index.html?path=$impl"
           tal:content="impl" /></code>
      </li>
    </ul>
  </div>

</body>
</html>

=== Added File Zope3/src/zope/products/apidoc/servicemodule/menu.pt ===
<html metal:use-macro="views/apidoc_macros/menu">
<body>

  <p metal:fill-slot="pre_menu" class="small">
    This is a list of all available services by name.
  </p>

</body>
</html>

=== Added File Zope3/src/zope/products/apidoc/servicemodule/tests.py ===
##############################################################################
#
# Copyright (c) 2004 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.0 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""Tests for the Service Documentation Module

$Id: tests.py,v 1.1 2004/01/29 17:51:17 srichter Exp $
"""
import unittest
from zope.testing.doctestunit import DocTestSuite
    
def test_suite():
    return unittest.TestSuite((
        DocTestSuite('zope.products.apidoc.servicemodule'),
        ))

if __name__ == '__main__':
    unittest.main()