Generated API docs for twisted.python.log are confusing

[predictive]

It's confusing that err is in twisted.python.log, but msg is in twisted.python.LogPublisher, and twisted.python.debug is deprecated. Since simplicity is the attractive part of twisted's logging vs python's, shouldn't debug be undeprecated and all three put in LogPublisher?

It would be even more attractive if twistd took a -v or --verbose switch that 'turned on' log.debug messages, so code doesn't have to be littered with "if self.debug: log.msg('foo')".

[spiv]

I'm not sure what exactly you mean:

>>> import sys
>>> from twisted.python import log
>>> log.startLogging(sys.stdout)
2006/05/05 18:29 EST [-] Log opened.
>>> log.msg('a msg')
2006/05/05 18:29 EST [-] a msg
>>> log.err('an error')
2006/05/05 18:29 EST [-] 'an error'

i.e. msg and err are both attributes of twisted.python.log.

Are you referring to the implementation of twisted/python/log.py being confusing, the generated API docs being confusing, to  http://twistedmatrix.com/projects/core/documentation/howto/logging.html being confusing, or something else? I want to make sure we understand what you mean.

The suggestion that we undeprecate twisted.python.log.debug, and add a --verbose switch belongs in a seperate enhancement ticket, I think. Big, multiple-issue tickets don't tend to get done. Call it something like "Proposal: standard debug logging API". I suspect the existing debug function was deprecated largely because it wasn't very carefully thought out how it would work.

Reassigning back to the reporter, for clarification.

[predictive]

My confusion stems from the generated API documentation. log() is at  http://twistedmatrix.com/documents/current/api/twisted.python.log.html, and msg() is at  http://twistedmatrix.com/documents/current/api/twisted.python.log.LogPublisher.html.

I'll add the enhancement ticket for twistd you suggest, and maybe take a crack at debug and twistd integration in a couple of weeks after I have a chance to read your coding guidelines and get more familiar with the codebase.

[spiv]

Reassigning to mwh for his thoughts. Can pydoctor do better here? The API docs ought to look more like the way  http://twistedmatrix.com/projects/core/documentation/howto/logging.html describes them.

[mwh]

Well, it can be bodged, of course, in the way that t.p.c.Interface is done now. I don't really see a way to make sensible API docs from the static source.

Expanding the module docstring might help :)

[mwh]

Well, what do you know, I've added some support for taking data from live objects in pydoctor svn. Currently it treats bound methods that turn up in module dictionaries like functions, which not entirely coincidentally is the case required to document twisted.python.log properly. See

 http://starship.python.net/crew/mwh/apidocs-s/twisted.python.log.html

Lots more potential for hacking ahead (and the integration is a bit crappy too so far).

[exarkun]

#2708 was a duplicate of this.

[zooko]

So, did the pydoctor hack that mwh mentioned in comment:6 work to make the hyperlink for log.msg on this page:  http://twistedmatrix.com/documents/current/core/howto/logging.html stop being a broken hyperlink to:  http://twistedmatrix.com/documents/10.0.0/api/twisted.python.log.msg.html ?

[exarkun]

#5247 was a duplicate of this.

[thijs]

Replying to zooko:

So, did the pydoctor hack that mwh mentioned in comment:6 work to make the hyperlink for log.msg on this page:  http://twistedmatrix.com/documents/current/core/howto/logging.html stop being a broken hyperlink to:  http://twistedmatrix.com/documents/10.0.0/api/twisted.python.log.msg.html ?

Yes, there are no broken links on the page anymore and it now links to  http://twistedmatrix.com/documents/11.0.0/api/twisted.python.log.LogPublisher.msg.html.

[glyph]

I just noticed this yet again.  http://twistedmatrix.com/documents/11.0.0/api/twisted.python.log.html still doesn't include a reference to log.msg. mwh, did the hack featured on  http://starship.python.net/crew/mwh/apidocs-s/twisted.python.log.html ever make it to trunk? are we generating the docs with an old version of pydoctor?