Add Sphinx documentation

Move doctest examples to API reference.

CHANGES.txt

@@ -5,6 +5,8 @@ CHANGES
 4.0.0 (unreleased)
 ------------------
 
+- Added Sphinx documentation:  moved doctest examples to API reference.
+
 - Added 'setup.py docs' alias (installs ``Sphinx`` and dependencies).
 
 - Added 'setup.py dev' alias (runs ``setup.py develop`` plus installs

docs/api.rst

+:mod:`zope.proxy` API
+=====================
+
+:mod:`zope.proxy.interfaces`
+----------------------------
+
+.. automodule:: zope.proxy.interfaces
+
+  .. autointerface:: IProxyIntrospection
+     :members:
+     :member-order: bysource
+
+
+:mod:`zope.proxy`
+-----------------
+
+.. automodule:: zope.proxy
+   :members:
+
+:mod:`zope.proxy.decorator`
+---------------------------
+
+.. automodule:: zope.proxy.decorator
+
+   .. doctest::
+
+      >>> from zope.interface import Interface
+      >>> from zope.interface import directlyProvides
+      >>> from zope.interface import implementer
+      >>> class I1(Interface):
+      ...     pass
+      >>> class I2(Interface):
+      ...     pass
+      >>> class I3(Interface):
+      ...     pass
+      >>> class I4(Interface):
+      ...     pass
+      >>> from zope.proxy.decorator import SpecificationDecoratorBase
+      >>> @implementer(I1)
+      ... class D1(SpecificationDecoratorBase):
+      ...   pass
+      >>> @implementer(I2)
+      ... class D2(SpecificationDecoratorBase):
+      ...   pass
+      >>> @implementer(I3)
+      ... class X(object):
+      ...   pass
+      >>> x = X()
+      >>> directlyProvides(x, I4)
+
+   Interfaces of X are ordered with the directly-provided interfaces first.
+
+   .. doctest::
+
+      >>> from zope.interface import providedBy
+      >>> [interface.getName() for interface in list(providedBy(x))]
+      ['I4', 'I3']
+
+   When we decorate objects, what order should the interfaces come
+   in?  One could argue that decorators are less specific, so they
+   should come last.
+
+   .. doctest::
+
+      >>> [interface.getName() for interface in list(providedBy(D1(x)))]
+      ['I4', 'I3', 'I1']
+
+      >>> [interface.getName() for interface in list(providedBy(D2(D1(x))))]
+      ['I4', 'I3', 'I1', 'I2']
+
+   SpecificationDecorators also work with old-style classes:
+
+   .. doctest::
+
+      >>> @implementer(I3)
+      ... class X:
+      ...   pass
+
+      >>> x = X()
+      >>> directlyProvides(x, I4)
+
+      >>> [interface.getName() for interface in list(providedBy(x))]
+      ['I4', 'I3']
+
+      >>> [interface.getName() for interface in list(providedBy(D1(x)))]
+      ['I4', 'I3', 'I1']
+
+      >>> [interface.getName() for interface in list(providedBy(D2(D1(x))))]
+      ['I4', 'I3', 'I1', 'I2']
+
+   .. autoclass:: DecoratorSpecificationDescriptor
+      :members:
+
+   .. autoclass:: SpecificationDecoratorBase

docs/conf.py

@@ -25,7 +25,14 @@ import sys, os
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.todo',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.viewcode',
+    'repoze.sphinx.autointerface',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/index.rst

@@ -6,6 +6,7 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   api
 
 
 Indices and tables

src/zope/proxy/decorator.py

@@ -26,67 +26,6 @@ from zope.interface import providedBy
 
 class DecoratorSpecificationDescriptor(ObjectSpecificationDescriptor):
     """Support for interface declarations on decorators
-
-    >>> from zope.interface import Interface
-    >>> from zope.interface import directlyProvides
-    >>> from zope.interface import implementer
-    >>> class I1(Interface):
-    ...     pass
-    >>> class I2(Interface):
-    ...     pass
-    >>> class I3(Interface):
-    ...     pass
-    >>> class I4(Interface):
-    ...     pass
-
-    >>> @implementer(I1)
-    ... class D1(SpecificationDecoratorBase):
-    ...   pass
-
-
-    >>> @implementer(I2)
-    ... class D2(SpecificationDecoratorBase):
-    ...   pass
-
-    >>> @implementer(I3)
-    ... class X(object):
-    ...   pass
-
-    >>> x = X()
-    >>> directlyProvides(x, I4)
-
-    Interfaces of X are ordered with the directly-provided interfaces first
-
-    >>> [interface.getName() for interface in list(providedBy(x))]
-    ['I4', 'I3']
-
-    When we decorate objects, what order should the interfaces come
-    in?  One could argue that decorators are less specific, so they
-    should come last.
-
-    >>> [interface.getName() for interface in list(providedBy(D1(x)))]
-    ['I4', 'I3', 'I1']
-
-    >>> [interface.getName() for interface in list(providedBy(D2(D1(x))))]
-    ['I4', 'I3', 'I1', 'I2']
-
-    SpecificationDecorators also work with old-style classes:
-
-    >>> @implementer(I3)
-    ... class X:
-    ...   pass
-
-    >>> x = X()
-    >>> directlyProvides(x, I4)
-
-    >>> [interface.getName() for interface in list(providedBy(x))]
-    ['I4', 'I3']
-
-    >>> [interface.getName() for interface in list(providedBy(D1(x)))]
-    ['I4', 'I3', 'I1']
-
-    >>> [interface.getName() for interface in list(providedBy(D2(D1(x))))]
-    ['I4', 'I3', 'I1', 'I2']
     """
     def __get__(self, inst, cls=None):
         if inst is None: