launchpad-dev team mailing list archive

[Gary Poster <gary.poster@xxxxxxxxxxxxx>]

On Jul 29, 2010, at 7:05 AM, Jonathan Lange wrote:

> On Wed, Jul 28, 2010 at 9:23 PM, Gary Poster <gary.poster@xxxxxxxxxxxxx> wrote:
>> Salgado has gotten the Zope apidoc to work to show Launchpad's code.  I think you all might find it useful.  I often have found the Zope-only version helpful, and this new version is custom to our own codebade.
>> 
>> People with access to devpad can just go to https://devpad.canonical.com/~gary to give it a whirl.
>> 
> 
> Very cool, thanks for doing this Gary & Salgado.
> 
> ...
>> - Click on the book link on the top left.  On the bottom left, look for the Launchpad section of the docs.  It has a few ReST docs that I knew were actual documentation.  It's easy to expose doctests like this, and I hope to eventually expose other docs, like the stuff from lazr.restful; if you want to add some docs here, let me know and I'll describe how to do it.  It's pretty easy.
> 
> I can't help but notice that there's some stuff there that's not
> relevant to Launchpad dev, ZODB for example. Is it possible to hide
> that?

Possible, of course.  Worth the effort, questionable.  

To get it hidden statically only, we can do some massaging of the generated HTML at one stage or another.

I'm not sure how to get it hidden dynamically.  apidoc itself registers those docs (http://svn.zope.org/zope.app.apidoc/trunk/src/zope/app/apidoc/bookmodule/book.zcml?view=auto at the bottom, FWIW).  I don't think overrides will work for this, but maybe.  I'll give it a whirl some evening, maybe.

> FWIW, the images and stylesheet on the public website point to
> apidoc.launchpad.dev:
>  https://apidoc.launchpad.dev/@@/apidoc.css
>  https://apidoc.launchpad.dev/@@/utilities.js

Ew.  Thanks for telling me; I must have had them cached.  I'll fix those up soonish one way or another (sed to the rescue, I suspect).

> ...
>> - Click on the code browser link on the top left.  Click on the "browse source code" in the link on the bottom left frame, or type in a name and click "Find".  Start browsing around.  You'll see everything is interlinked as you browse.
> 
> Very neat.
> 
> If I wanted to make this understand epytext, where would I start?

You'd start with the zope.app.apidoc source (there's a project for the code on LP, https://bugs.edge.launchpad.net/zope.app.apidoc, but no import yet; the source is svn://svn.zope.org/repos/main/zope.app.apidoc/trunk/).

Digging around in there briefly, it seemed like you might follow this path:

src/zope/app/apidoc/codemodule/ ...
src/zope/app/apidoc/codemodule/browser ...
zope.app.apidoc.utilities.renderText *stuff might need to happen here or in callers to this function so that epydoc is tried in some cases or other; this is probably the part that would involve some ingenuity, since there are typically no markers to distinguish the formatting of a given text blob*

Then you would dig into the zope.app.renderer package to see how the rest, plaintext, and structuredtext renderes are set up, and make an epydoc version.  This part would probably be pretty straightforward.  For instance, here's the ReST version: http://svn.zope.org/zope.app.renderer/trunk/src/zope/app/renderer/rest.py?view=auto .  Here's the pertinent configure.zcml: http://svn.zope.org/zope.app.renderer/trunk/src/zope/app/renderer/configure.zcml?view=auto .  Doesn't look bad at all to me.

Gary