Generating more useful Python API docs

[Jonathan Robie <jo...@redhat.com>]

I'm trying to figure out if there is a relatively easy way to generate 
more useful Python API docs.

Many of the methods you actually want to use are created when loading 
the spec files at run time, and do not show up in the pydoc. That makes 
it pretty hard to know what methods you can call by looking at the pydoc.

I suppose one approach would be to creat HTML files using pydoc, then 
merge in some information from the spec files. Are there other 
approaches worth considering?

Jonathan

Re: Generating more useful Python API docs

[Jonathan Robie <jo...@redhat.com>]

i can create a lot better Python docs by enumerating the starting points 
we care about. This incantation seems to work for me:

$ epydoc -v -u http://qpid.apache.org -n "Apache Qpid: Open Source AMQP 
Enterprise Messaging" qpid.session qpid.connection qpid.datatypes 
qpid.exceptions qmf.console

I'll try to find an appropriate place on the Wiki to enshrine that 
knowledge.

Jonathan

---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project:      http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org

Re: Generating more useful Python API docs

[Jonathan Robie <jo...@redhat.com>]

Jonathan Robie wrote:
> Ted Ross wrote:
>> I seem to recall using a tool called amqp-doc (in qpid/python) to 
>> generate pydoc-style output for the AMQP specification.  This output 
>> included the "generated" parts of the API.
>>
>> Unfortunately, that tool doesn't seem to work in the latest SVN.
>
> Ideally, I'd like to find a way to produce documentation that shows me 
> whatever I can call in Python, generated or not, in one place. I'll 
> look at amqp-doc to see what it did.

Here's what I found:

1. The last version of amqp-doc that worked seemed to be around version 2.1
2. The underlying data structures have changed since then, which broke 
the amqp-doc tool
3. The methods I want to document are not instantiated when the spec is 
first loaded, they seem to be instantiated when first invoked. Rafi is 
on vacation, so I have to wait for him to return and verify that. But if 
I understand this correctly, there's nothing for pydoc to see unless I 
force each method to be instantiated.

At this point, generating complete Python API docs seems to be a 
non-trivial exercise. If I'm wrong, I'm sure Rafi will point it out and 
I'll give it another try on Monday.

Jonathan

Re: Generating more useful Python API docs

[Jonathan Robie <jo...@redhat.com>]

Ted Ross wrote:
> I seem to recall using a tool called amqp-doc (in qpid/python) to 
> generate pydoc-style output for the AMQP specification.  This output 
> included the "generated" parts of the API.
>
> Unfortunately, that tool doesn't seem to work in the latest SVN.

Ideally, I'd like to find a way to produce documentation that shows me 
whatever I can call in Python, generated or not, in one place. I'll look 
at amqp-doc to see what it did.

I actually tried writing a program that loaded the spec and then called 
the pydoc API, but that didn't show the generated methods. Worth a try ;->

Jonathan

Re: Generating more useful Python API docs

[Ted Ross <tr...@redhat.com>]

Jonathan Robie wrote:
> I'm trying to figure out if there is a relatively easy way to generate 
> more useful Python API docs.
>
> Many of the methods you actually want to use are created when loading 
> the spec files at run time, and do not show up in the pydoc. That 
> makes it pretty hard to know what methods you can call by looking at 
> the pydoc.
>
> I suppose one approach would be to creat HTML files using pydoc, then 
> merge in some information from the spec files. Are there other 
> approaches worth considering?
>
> Jonathan
Jonathan,

I seem to recall using a tool called amqp-doc (in qpid/python) to 
generate pydoc-style output for the AMQP specification.  This output 
included the "generated" parts of the API.

Unfortunately, that tool doesn't seem to work in the latest SVN.

-Ted