[Twisted-Python] epydoc and Twisted
I've done a first pass at building Twisted docs with epydoc. It can be seen here: http://day.cubik.org/~bruce/twisted/epydoc/twisted.html The command line that I'm using to do that is: python2.1 /usr/lib/python2.1/site-packages/epydoc/cli.py -o doc/epydoc -n Twisted -vvvv `find twisted -name \*.py | grep -v test | grep -v gtk | grep -v jyac | grep -v java | grep -v qt | grep -v ssl | grep -v win32 | grep -v wxsup | grep -v kqre | grep -v pywid | grep -v gnome | grep -v native | grep -v mktap | grep -v manhole | grep -v tktree | grep -v tkutil | grep -v ssh | grep -v xmlrpc | grep -v /reactor.py | grep -v /mail/` which is quite a mess. The problem is that since it imports the files, any missing dependencies and so on will cause it to bomb. (/mail/ is excluded because it triggered an epydoc bug and I couldn't care enough yet to look and fix it.) There were tons of warnings/errors from epydoc which I've logged and I'll start looking at that soon (over the next day or so). Thoughts on how we should deal with the import problem are welcome. Is that a roadblock in the way of switching from happydoc to epydoc? - Bruce
Bruce Mitchener wrote:
This is *great*! Much better than the happydoc, and better than pydoc, which I've been using locally. Any chance you could put a tar or zip of this on your website so I don't beat it to death? :^) (Glyph: sorry about the duped messages again -- I forgot to change my identity from sending to another list ... I need to change my other subscriptions!) Thanks! -- Steve.
On Thu, 2002-08-22 at 11:59, Bruce Mitchener wrote:
Thoughts on how we should deal with the import problem are welcome. Is that a roadblock in the way of switching from happydoc to epydoc?
I have no response to your question, but I have some comments to make. 1. converting generate-domdocs to use epydoc seems it'll be really easy -- it'll just require a slightly modified regexp-builder, afaics. I'll get to that soon. 2. I hope we're going to start using the @foo mechanisms that epydoc uses in Twisted -- it'll make our API references much more information-rich. Does anyone have any problems with that? -- Chris Armstrong << radix@twistedmatrix.com >> http://twistedmatrix.com/users/radix.twistd/
Christopher Armstrong wrote:
Cool, I didn't really want to do that.
I hope not. I'd be very disappointed. The informatation that they've been providing in work docs has been a big help. I do wish that epydoc generated more internal links .. might be a good thing for someone to add. I've got some other epydoc patches that I'll end up contributing I guess. - Bruce
On Thu, 22 Aug 2002 12:12:49 -0600, Bruce Mitchener <bruce@cubik.org> wrote:
"It's not just a good idea, it's the law." This should be in the coding standard. While I wouldn't take a lot of developer time that might be better spent elsewhere to go through and insert this meta-information, we really ought to be getting the most out of the documentation system we use. We should also write a silly hack to allow any module to import without ImportErrors. I think this would fix most of the doc generation issues? -- | <`'> | Glyph Lefkowitz: Travelling Sorcerer | | < _/ > | Lead Developer, the Twisted project | | < ___/ > | http://www.twistedmatrix.com |
Glyph Lefkowitz wrote:
Good good. I'll make those changes to the standards.
We should also write a silly hack to allow any module to import without ImportErrors. I think this would fix most of the doc generation issues?
This takes more Python clue than I'v currently been gifted with. :) I'll see about scaring up some work out of dash, radix, itamar, or some other local smartie. - Bruce
"Christopher" == Christopher Armstrong <radix@twistedmatrix.com> writes:
> 2. I hope we're going to start using the @foo mechanisms that > epydoc uses in Twisted -- it'll make our API references much > more information-rich. Does anyone have any problems with that? Some of us already have. Look at twisted.issues. :)
Bruce Mitchener wrote:
This is *great*! Much better than the happydoc, and better than pydoc, which I've been using locally. Any chance you could put a tar or zip of this on your website so I don't beat it to death? :^) (Glyph: sorry about the duped messages again -- I forgot to change my identity from sending to another list ... I need to change my other subscriptions!) Thanks! -- Steve.
On Thu, 2002-08-22 at 11:59, Bruce Mitchener wrote:
Thoughts on how we should deal with the import problem are welcome. Is that a roadblock in the way of switching from happydoc to epydoc?
I have no response to your question, but I have some comments to make. 1. converting generate-domdocs to use epydoc seems it'll be really easy -- it'll just require a slightly modified regexp-builder, afaics. I'll get to that soon. 2. I hope we're going to start using the @foo mechanisms that epydoc uses in Twisted -- it'll make our API references much more information-rich. Does anyone have any problems with that? -- Chris Armstrong << radix@twistedmatrix.com >> http://twistedmatrix.com/users/radix.twistd/
Christopher Armstrong wrote:
Cool, I didn't really want to do that.
I hope not. I'd be very disappointed. The informatation that they've been providing in work docs has been a big help. I do wish that epydoc generated more internal links .. might be a good thing for someone to add. I've got some other epydoc patches that I'll end up contributing I guess. - Bruce
On Thu, 22 Aug 2002 12:12:49 -0600, Bruce Mitchener <bruce@cubik.org> wrote:
"It's not just a good idea, it's the law." This should be in the coding standard. While I wouldn't take a lot of developer time that might be better spent elsewhere to go through and insert this meta-information, we really ought to be getting the most out of the documentation system we use. We should also write a silly hack to allow any module to import without ImportErrors. I think this would fix most of the doc generation issues? -- | <`'> | Glyph Lefkowitz: Travelling Sorcerer | | < _/ > | Lead Developer, the Twisted project | | < ___/ > | http://www.twistedmatrix.com |
Glyph Lefkowitz wrote:
Good good. I'll make those changes to the standards.
We should also write a silly hack to allow any module to import without ImportErrors. I think this would fix most of the doc generation issues?
This takes more Python clue than I'v currently been gifted with. :) I'll see about scaring up some work out of dash, radix, itamar, or some other local smartie. - Bruce
"Christopher" == Christopher Armstrong <radix@twistedmatrix.com> writes:
> 2. I hope we're going to start using the @foo mechanisms that > epydoc uses in Twisted -- it'll make our API references much > more information-rich. Does anyone have any problems with that? Some of us already have. Look at twisted.issues. :)
participants (6)
-
Allen Short -
Bruce Mitchener -
Christopher Armstrong -
Glyph Lefkowitz -
R. Church -
Steve Waterbury