Suggestions for the generated API reference documentation

[Michael Hudson]

Nicholas Allen wrote:
> Hi,
> 
> I find using the API reference for the Bazaar API really cumbersome and
> time consuming.  This is mainly because it includes all the test code as
> well as the actual BzrLib API. This makes finding something much more of
> a problem.

How are you finding things?  I generally start at the package root and
drill down from there, I can see that if you're using one of the indices
that the test stuff would be a clutter.

> It would be nice if the API could be generated separately for
> the Bzr lib API and for the test cases.

This is certainly possible.

> The format is also really bad compared to other API generated documents.

Well hey, _I_ like it, which is no surprise given that I wrote the tool
that produces it :)

> I don't know if this is a problem with the API document generators for
> Python or if this can be configured to produce something sane (I hope
> so). Something like what JavaDoc produces would be much better.

Please explain your definition of "sane".  FWIW, I find what epydoc
produces extremely hard to navigate, and have never used javadoc.

I've not worked much on pydoctor lately, but I'm happy to try to make it
"better" if you explain what "better" means to you :)

Cheers,
mwh