[Zope-dev] Sphinx extension for zope.interface?

[Kevin Teague]

On Oct 3, 2008, at 12:06 PM, Tres Seaver wrote:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Tres Seaver wrote:
>> Has anybody packaged up an extension to allow extracting APIs /
>> docstrings cleanly from Zope interfaces in Sphinx?  I found Chris
>> McDonough's patch from back in April, but it no longer applies  
>> cleanly,
>> and besides, as he notes, it should really be done as a standalone
>> extension.
>
> Scratching my own itch:
>
>  http://pypi.python.org/pypi/repoze.sphinx.autointerface/
>
>

Nice!

I've been playing with this since I wanted to start using the  
sphinx.ext.autoclass (and now repoze.sphinx.autointerface) to generate  
the Grok docs.

However, the HTML differs between autoclass and autointerface - it'd  
be nice it they were more similar. In particular:

  *  <dl class="interface"> is needed to style the block.
  * The word "Interface:" should have a <span class="interfacelabel">  
or something around it so that it can be hidden using CSS if desired.
  * <tt class="descinterfacename"> and <tt class="descname">
  * Permalinks (those wierd-o backwards P characters ¶) are missing

And looking at the source it looks like it the package mostly just  
slots in the docutils-generated HTML - so I guess it could take some  
wrangling to make changes to the generated HTML ...

One other small thing, the install_requires for the package doesn't  
declare that it requires docutils >= 0.5.


autoclass html
-------------------

<dl class="class">
<dt id="grok.Application">
<!--[grok.Application]-->class <tt class="descclassname">grok.</tt><tt  
class="descname">Application</tt><a class="headerlink"  
href="#grok.Application" title="Permalink to this definition">¶</a></dt>
<dd>A top-level application object.</dd></dl>


autointerface html
------------------------

<dl class="docutils">
<dt>Interface: <tt class="docutils literal"><span  
class="pre">grok.interfaces.IApplication</span></tt></dt>
<dd><p class="first">Marker-interface for grok application factories.</ 
p>
<p class="last">Used to register applications as utilities to look  
them up and provide a
list of grokked applications.</p>
</dd>
</dl>