More documentation fixes; prep 0.1.2 release.

CHANGES.txt

@@ -1,6 +1,11 @@
 repoze.sphinx.autointerface Changelog
 =====================================
 
+0.1.2 (2008-10-03)
+------------------
+
+- Packaging change:  improved description in README.txt.
+
 0.1.1 (2008-10-03)
 ------------------
 

README.txt

@@ -5,19 +5,34 @@ Overview
 --------
 
 Thie package defines an extension for the
-`Sphinx <http://sphinx.pocool.org>`_ documentation system.
+`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`` or any other mechanism to get the
-package on the path.
+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 ``conf.py`` of the docs
-section of your product.
+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
 -------------------
@@ -26,4 +41,15 @@ At appropriate points in your document, call out the interface
 autodocs via::
 
   .. autoinclude:: yourpackage.interfaces.IFoo
-     :members:
+
+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).