repoze-sphinx-autointerface 0.3

Sphinx extension: auto-generates API docs from Zope interfaces

repoze.sphinx.autointerface README
==================================

Overview
--------

Thie package defines an extension for the
`Sphinx <http://sphinx.pocool.org>`_ documentation system. The extension
allows generation of API documentation by introspection of
`zope.interface <http://pypi.python.org/pypi/zope.interface>`_ instances in
code.


Installation
------------

Install via `easy_install
<http://peak.telecommunity.com/DevCenter/EasyInstall>`_::

$ bin/easy_install repoze.sphinx.autointerface

or any other means which gets the package on your ``PYTHONPATH``.


Registering the Extension
-------------------------

Add ``repoze.sphinx.autointerface`` to the ``extensions`` list in the
``conf.py`` of the Sphinx documentation for your product. E.g.::

extensions = ['sphinx.ext.autodoc',
'sphinx.ext.doctest',
'repoze.sphinx.autointerface',
]


Using the Extension
-------------------

At appropriate points in your document, call out the interface
autodocs via::

.. autointerface:: yourpackage.interfaces.IFoo

Output from the directive includes

- the fully-qualified interface name
- any base interfaces
- the doctstring from the interface, rendered as reSTX.
- the members of the interface (methods and attributes).

* For each attribute, the output includes the attribute name
and its description.
* For each method, the output includes the method name, its signature,
and its docstring (also rendered as reSTX).


repoze.sphinx.autointerface Changelog
=====================================

0.3 (2009-10-25)
----------------

- Refactor sphinx integration. There are now separate ``autointerface``
and ``interface`` directives.

0.2.1 (2009-08-20)
----------------

- Fix add_directive arguments to work with Sphinx 0.6.1, now required.

0.1.3 (2009-01-14)
------------------

- Coerce unicode path elements to str in ``_resolve_dotted_name``.
Note that non-ASCII path elements won't work: this fix just deals
with the case where the path was of type unicode.

- Fixed spelling of directive in README.txt.

- Added dependency on ``zope.interface``.

0.1.2 (2008-10-03)
------------------

- Packaging change: improved description in README.txt.

0.1.1 (2008-10-03)
------------------

- Packaging bug: the ``long_description`` was not rendering properly to
HTML on PyPI.

0.1 (2008-10-02)
----------------

- Initial release.