Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Apr 14, 2010, at 09:59 AM, Bill Janssen wrote: >I've been using this for a bit -- three 1200x1600 monitors in portrait >mode driven by a Mac Pro. Not bad, but at my boss's urging I've >recently replaced two of them with an Apple 30" Cinema display. Bit >more resolution, 2560x1600, but I find

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Apr 14, 2010, at 11:50 PM, Georg Brandl wrote: >Am 14.04.2010 17:46, schrieb Barry Warsaw: >> I agree. Right now I've got enough big PEPs on my plate that I'm not >> willing to take on another one right now. Maybe I've sufficiently >> tempted/goaded/guilted/excited someone else to though. ;)

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

Am 14.04.2010 17:46, schrieb Barry Warsaw: > On Apr 14, 2010, at 05:37 PM, Michael Foord wrote: > >>Well, perhaps move this discussion to python-dev with the intent of >>creating a PEP and asking for BDFL pronouncement? The two contenders >>seem to be numpy format and epydoc format. We seem to h

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

Fred Drake wrote: > On Wed, Apr 14, 2010 at 11:53 AM, Georg Brandl wrote: > > Uh, or just use an editor that can usefully display three files > > side-by-side. > > Hmmm... Three monitors, each with three files side by side, oriented > vertically. More monitors for email and browsers, of cour

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Wed, Apr 14, 2010 at 11:46:11AM -0400, Mary S. Murphy wrote: > Please get your email addresses correct. I keep getting them. Thanks. I've removed her from the list. --amk ___ Doc-SIG maillist - Doc-SIG@python.org http://mail.python.org/mailman/lis

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Wed, Apr 14, 2010 at 11:53 AM, Georg Brandl wrote: > Uh, or just use an editor that can usefully display three files side-by-side. Hmmm... Three monitors, each with three files side by side, oriented vertically. More monitors for email and browsers, of course. Sounds like an ideal coding pl

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On 14/04/2010 17:53, Georg Brandl wrote: Am 14.04.2010 15:25, schrieb Michael Foord: On 14/04/2010 17:24, Fred Drake wrote: On Wed, Apr 14, 2010 at 11:13 AM, Ralf Gommers wrote: You're a core developer (I think). But for the *average* user, do you really think tags are fi

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On 14/04/2010 17:41, Barry Warsaw wrote: On Apr 14, 2010, at 04:56 PM, Michael Foord wrote: I would say that reading docstrings in a terminal is the *main* use case - but that is why I tend to value the vertical space highly and personally prefer the less verbose way. I agree about t

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

Am 14.04.2010 15:25, schrieb Michael Foord: > On 14/04/2010 17:24, Fred Drake wrote: >> On Wed, Apr 14, 2010 at 11:13 AM, Ralf Gommers >> wrote: >> >>> You're a core developer (I think). But for the *average* user, do you really >>> think tags are fine? Earlier in this thread there was a ment

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

Please get your email addresses correct. I keep getting them. Thanks. - Original Message - From: Michael Foord To: Ralf Gommers Cc: doc-sig@python.org Sent: Wednesday, April 14, 2010 11:22 AM Subject: Re: [Doc-SIG] epydoc reST markup for stdlib docstrings On 14/04/2010

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Apr 14, 2010, at 05:37 PM, Michael Foord wrote: >Well, perhaps move this discussion to python-dev with the intent of >creating a PEP and asking for BDFL pronouncement? The two contenders >seem to be numpy format and epydoc format. We seem to have a consensus >that adopting a standard for the

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Apr 14, 2010, at 11:13 PM, Ralf Gommers wrote: >You're a core developer (I think). But for the *average* user, do you really >think tags are fine? Earlier in this thread there was a mention of people >that love to read XML. I'm exaggerating a bit of course, but this is >similar. Whitespace beat

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Apr 14, 2010, at 04:56 PM, Michael Foord wrote: >I would say that reading docstrings in a terminal is the *main* use case >- but that is why I tend to value the vertical space highly and >personally prefer the less verbose way. I agree about the vertical whitespace when reading in the termin

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On 14/04/2010 16:07, Barry Warsaw wrote: On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote: Barry Warsaw wrote: On Apr 14, 2010, at 01:30 AM, Michael Foord wrote: Definite +1 from me on adopting reST in docstrings as a standard. I haven't looked at the Epydoc convention for

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Wed, Apr 14, 2010 at 11:22 PM, Michael Foord wrote: > On 14/04/2010 17:13, Ralf Gommers wrote: > > > > On Wed, Apr 14, 2010 at 10:56 PM, Michael Foord > wrote: > >> On 14/04/2010 16:48, Ralf Gommers wrote: >> >> The vertical whitespace vs tags is a taste issue, I agree, from a >> developer

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Wed, Apr 14, 2010 at 11:25 AM, Michael Foord wrote: > They're great if you turn them sideways though... Indeed they are! All monitors are improved in that arrangement. -Fred -- Fred L. Drake, Jr. "Chaos is the score upon which reality is written." --Henry Miller

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On 14/04/2010 17:24, Fred Drake wrote: On Wed, Apr 14, 2010 at 11:13 AM, Ralf Gommers wrote: You're a core developer (I think). But for the *average* user, do you really think tags are fine? Earlier in this thread there was a mention of people that love to read XML. I'm exaggerating a bit

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Wed, Apr 14, 2010 at 11:13 AM, Ralf Gommers wrote: > You're a core developer (I think). But for the *average* user, do you really > think tags are fine? Earlier in this thread there was a mention of people > that love to read XML. I'm exaggerating a bit of course, but this is > similar. Whitesp

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On 14/04/2010 17:13, Ralf Gommers wrote: On Wed, Apr 14, 2010 at 10:56 PM, Michael Foord mailto:fuzzy...@voidspace.org.uk>> wrote: On 14/04/2010 16:48, Ralf Gommers wrote: The vertical whitespace vs tags is a taste issue, I agree, from a developer perspective. From a user perspe

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Wed, Apr 14, 2010 at 10:56 PM, Michael Foord wrote: > On 14/04/2010 16:48, Ralf Gommers wrote: > > The vertical whitespace vs tags is a taste issue, I agree, from a developer > perspective. From a user perspective however, the numpy standard is clearly > more readable in a terminal. That's why

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On 14/04/2010 16:48, Ralf Gommers wrote: On Wed, Apr 14, 2010 at 10:23 PM, Georg Brandl > wrote: Am 14.04.2010 14:07, schrieb Barry Warsaw: > On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote: > >>Barry Warsaw wrote: >>> On Apr 14, 2010, at 01:30 AM

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Wed, Apr 14, 2010 at 10:39 PM, Fred Drake wrote: > On Wed, Apr 14, 2010 at 10:26 AM, Georg Brandl wrote: > > That was a more interesting task :) However, I'm not opposed to doing > > stupid, repetitive things every now and then, and I hope I can find a > > few others to share the task. > > A

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Wed, Apr 14, 2010 at 10:23 PM, Georg Brandl wrote: > Am 14.04.2010 14:07, schrieb Barry Warsaw: > > On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote: > > > >>Barry Warsaw wrote: > >>> On Apr 14, 2010, at 01:30 AM, Michael Foord wrote: > >>> > Definite +1 from me on adopting reST in docstr

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Wed, Apr 14, 2010 at 10:39 AM, Michael Foord wrote: > Right - and included in the contract can be details like what exceptions an > API raises. We don't necessarily need a standard to specify that (?) but it > is the sort of information that ought to be in docstrings where relevant. Yep. I wa

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Wed, Apr 14, 2010 at 10:26 AM, Georg Brandl wrote: > That was a more interesting task :)  However, I'm not opposed to doing > stupid, repetitive things every now and then, and I hope I can find a > few others to share the task. Agreed the task was more interesting. Also, I wasn't suggesting t

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On 14/04/2010 16:37, Fred Drake wrote: On Wed, Apr 14, 2010 at 10:27 AM, Nick Coghlan wrote: The ", optional" parts seem rather redundant (since they are implied by the function signature itself), but the guidelines say to include them, so I included them. It seems to me that the exceptiona

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Wed, Apr 14, 2010 at 10:27 AM, Nick Coghlan wrote: > The ", optional" parts seem rather redundant (since they are implied by > the function signature itself), but the guidelines say to include them, > so I included them. It seems to me that the exceptional keyword > arguments are those which ar

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

Am 14.04.2010 13:08, schrieb Fred Drake: > On Wed, Apr 14, 2010 at 8:44 AM, Michael Foord > wrote: >> I too would prefer a consistent pattern be adopted for the Python standard >> library. Good luck finding someone to go and change all the docstrings in >> the standard library to use it... > > We

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

Barry Warsaw wrote: > Here's an example: > > def inject_message(mlist, msg, recips=None, switchboard=None, **kws): > """Inject a message into a queue. > > :param mlist: The mailing list this message is destined for. > :type mlist: `IMailingList` > :param msg: The message object to

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

Am 14.04.2010 14:07, schrieb Barry Warsaw: > On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote: > >>Barry Warsaw wrote: >>> On Apr 14, 2010, at 01:30 AM, Michael Foord wrote: >>> Definite +1 from me on adopting reST in docstrings as a standard. I haven't looked at the Epydoc convention

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Apr 14, 2010, at 11:58 PM, Nick Coghlan wrote: >Barry Warsaw wrote: >> On Apr 14, 2010, at 01:30 AM, Michael Foord wrote: >> >>> Definite +1 from me on adopting reST in docstrings as a standard. I >>> haven't looked at the Epydoc convention for parameters (etc) well enough >>> to have an opi

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

Barry Warsaw wrote: > On Apr 14, 2010, at 01:30 AM, Michael Foord wrote: > >> Definite +1 from me on adopting reST in docstrings as a standard. I >> haven't looked at the Epydoc convention for parameters (etc) well enough >> to have an opinion on that. > > The thing I like about them is that th

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Wed, Apr 14, 2010 at 8:44 AM, Michael Foord wrote: > I too would prefer a consistent pattern be adopted for the Python standard > library. Good luck finding someone to go and change all the docstrings in > the standard library to use it... We found someone interested in converting the LaTeX to

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Apr 14, 2010, at 02:44 PM, Michael Foord wrote: >I'm not aware of other formats beyond epydoc and javadoc (I agree with >your opinion on javadoc) - oh and the .NET xml format which I strongly >recommend we steer clear of. Do you have any references? XML is not human readable or writable (IMN

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On 14/04/2010 13:38, Barry Warsaw wrote: On Apr 13, 2010, at 08:55 PM, David Goodger wrote: I'm not a fan of epydoc's conventions (too much like JavaDoc, too verbose, too strict). On the other hand, "now is better than never" -- working code and rough consensus rule. I wouldn't object to ma

Re: [Doc-SIG] epydoc reST markup for stdlib docstrings

On Apr 13, 2010, at 08:55 PM, David Goodger wrote: >I'm not a fan of epydoc's conventions (too much like JavaDoc, too >verbose, too strict). On the other hand, "now is better than never" -- >working code and rough consensus rule. I wouldn't object to making the >epydoc field conventions *a* standa