Re: [Python-Dev] query: docstring formatting in python distutils code

[Georg Brandl]

Am 16.07.2010 22:55, schrieb Terry Reedy:
> On 7/7/2010 2:27 PM, Georg Brandl wrote:
>> Am 07.07.2010 19:53, schrieb Éric Araujo:
 I promised to write a PEP about that some time in the future.  (Probably 
 after
 3.2 final.)
> 
>>> It seems that projects putting Sphinxy reST in their doc are using
>>> automatic doc generation. This is however not always the best way to
>>> make good doc, as demonstrated by Python’s hand-written,
>>> very-high-quality documentation.
> 
>> I know, and this is what I originally intended for Sphinx.  However, the 
>> calls
>> for automatic doc generation are very loud, and it's understandable that most
>> project can't afford writing their documentation twice.
> 
> Neither can CPython, really, as evidenced by numerous examples that have 
> shone up on the tracker. Let me add another one. A week ago, Eli 
> Benderdky asked me for help adding missing pieces to the trace module 
> doc. The result so far is
> http://bugs.python.org/issue9264
> 
> After getting that far, I noticed that there were already doc strings 
> for some things that were not documented in the manual, which we added. 
> I also noticed the the public methods already in the manual had not help 
> strings, and hence no helpful help() output. In other words, the manual 
> entries and doc strings were close to disjoint sets.

And that's a pity -- very commendable that you work on this.  But this is
a single case, and most of our library is very well covered by the docs
and docstrings.  Additions (which usually are small amendments) are made
only in the docs, not the docstring, as it should be given the nature of
our docstrings.  Added functionality is usually documented first in
docstrings, which then get copied into the docs, and are padded from there.

> Even when they do overlap as they should, violation of DRY is a 
> maintenance nightmare when anything changes. It would be better if the 
> manual could, to some extent, be docstrings plus additions.

That sounds nice in theory, but opens another can of worms: what belongs
in the docstring, what in the "addition"?  How does it work for builtin
types, for language features, and so on.  Also, the problems I already
outlined in my answer to Fred remain...

Georg

-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Terry Reedy]

On 7/7/2010 2:27 PM, Georg Brandl wrote:

Am 07.07.2010 19:53, schrieb Éric Araujo:

I promised to write a PEP about that some time in the future.  (Probably after
3.2 final.)



It seems that projects putting Sphinxy reST in their doc are using
automatic doc generation. This is however not always the best way to
make good doc, as demonstrated by Python’s hand-written,
very-high-quality documentation.



I know, and this is what I originally intended for Sphinx.  However, the calls
for automatic doc generation are very loud, and it's understandable that most
project can't afford writing their documentation twice.


Neither can CPython, really, as evidenced by numerous examples that have 
shone up on the tracker. Let me add another one. A week ago, Eli 
Benderdky asked me for help adding missing pieces to the trace module 
doc. The result so far is

http://bugs.python.org/issue9264

After getting that far, I noticed that there were already doc strings 
for some things that were not documented in the manual, which we added. 
I also noticed the the public methods already in the manual had not help 
strings, and hence no helpful help() output. In other words, the manual 
entries and doc strings were close to disjoint sets.


Even when they do overlap as they should, violation of DRY is a 
maintenance nightmare when anything changes. It would be better if the 
manual could, to some extent, be docstrings plus additions.


--
Terry Jan Reedy


___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Ron Adam]

On 07/07/2010 12:30 PM, Georg Brandl wrote:

Am 07.07.2010 18:09, schrieb Michael Foord:


I would say that the major use of docstrings is for interactive help - so
interactive readability should be *the most important* (but perhaps not only)
factor when considering how to format standard library docstrings.


Agreed.  However, reST doesn't need to be less readable if the specific
inline markup is not used.  For example, using `identifier` to refer to a
function or *var* to refer to a variable (which is already done at quite a
few places) is very readable IMO.  Using ``code`` also isn't bad, considering
that double quotes are not much different and potentially ambiguous.

Overall, I think that we can make stdlib docstrings valid reST -- even if it's
reST without much markup -- but valid, so that people pulling in stdlib doc-
strings into Sphinx docs won't get ugly warnings.

What I would *not* like to see is heavy markup and Sphinx specifics -- that
would only make sense if we included the docstrings in the docs, and I don't
see that coming.


I also agree that interactive help should be the most important factor when 
writing doc strings for the standard library.


Are there any plans to change how pydoc's GUI mode works?  Could it use a 
minimal set of reST to improve it's display?


The patch I submitted (*which is waiting to be reviewed) extends the GUI 
mode so it can show the same info that is available from the help() function.


http://bugs.python.org/issue2001

I think the only issues with this patch are what new functions and classes 
should be part of the public api.



* BTW... The bug trackers main links to items with patches, and needing 
review, doesn't pick up feature requests.


Ron







___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Barry Warsaw]

On Jul 09, 2010, at 11:55 AM, Brett Cannon wrote:

>I think this is going to be something our crazy FLUFL likes but the
>kids don't. =)

Don't worry.  If you're lucky, you'll get old too.  Your eyes will go bad and
your mind will think more about tapioca.  By then you might even remember that
the FLUFL was right after all.

:)

-Barry


signature.asc
Description: PGP signature
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Brett Cannon]

On Fri, Jul 9, 2010 at 06:28, Barry Warsaw  wrote:
> On Jul 07, 2010, at 12:50 PM, Brett Cannon wrote:
>
>>On Wed, Jul 7, 2010 at 11:46, Antoine Pitrou 
>>wrote:
>>> On Wed, 7 Jul 2010 14:12:17 -0400
>>> Barry Warsaw  wrote:
 On Jul 07, 2010, at 07:30 PM, Georg Brandl wrote:

 >Overall, I think that we can make stdlib docstrings valid reST --
 >even if it's reST without much markup -- but valid, so that people
 >pulling in stdlib doc- strings into Sphinx docs won't get ugly
 >warnings.
 >
 >What I would *not* like to see is heavy markup and Sphinx
 >specifics -- that would only make sense if we included the
 >docstrings in the docs, and I don't see that coming.

 Does it make sense to add (reST-style) epydoc markup for API
 signatures? E.g.
>>>
>>> It really looks ugly (and annoying to decipher) when viewed in plain
>>> text.
>>
>>I agree. And it is highly repetitive since the signature information
>>is right there already. All of that info in those annotations can
>>easily be written in paragraph form if needed and honestly would read
>>better to my eyes.
>
> I actually find it easier to glean the signature details from a regularized
> docstring than from prose.  Especially for autogenerated API documentation,
> the formal specification lends a consistency to the output that prose doesn't
> often provide.  IME, there isn't much (unnecessary) repeating yourself.

The key point there is "autogenerated API documentation", which Python
does not do.

>
> Either way, we need to be diligent in accurately describing the signature and
> semantics of our APIs.

Of course.

I think this is going to be something our crazy FLUFL likes but the
kids don't. =)

-Brett

>
> -Barry
>
> ___
> Python-Dev mailing list
> Python-Dev@python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: 
> http://mail.python.org/mailman/options/python-dev/brett%40python.org
>
>
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Barry Warsaw]

On Jul 07, 2010, at 12:50 PM, Brett Cannon wrote:

>On Wed, Jul 7, 2010 at 11:46, Antoine Pitrou 
>wrote:
>> On Wed, 7 Jul 2010 14:12:17 -0400
>> Barry Warsaw  wrote:
>>> On Jul 07, 2010, at 07:30 PM, Georg Brandl wrote:
>>>
>>> >Overall, I think that we can make stdlib docstrings valid reST --
>>> >even if it's reST without much markup -- but valid, so that people
>>> >pulling in stdlib doc- strings into Sphinx docs won't get ugly
>>> >warnings.
>>> >
>>> >What I would *not* like to see is heavy markup and Sphinx
>>> >specifics -- that would only make sense if we included the
>>> >docstrings in the docs, and I don't see that coming.
>>>
>>> Does it make sense to add (reST-style) epydoc markup for API
>>> signatures? E.g.
>>
>> It really looks ugly (and annoying to decipher) when viewed in plain
>> text.
>
>I agree. And it is highly repetitive since the signature information
>is right there already. All of that info in those annotations can
>easily be written in paragraph form if needed and honestly would read
>better to my eyes.

I actually find it easier to glean the signature details from a regularized
docstring than from prose.  Especially for autogenerated API documentation,
the formal specification lends a consistency to the output that prose doesn't
often provide.  IME, there isn't much (unnecessary) repeating yourself.

Either way, we need to be diligent in accurately describing the signature and
semantics of our APIs.

-Barry


signature.asc
Description: PGP signature
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Fred Drake]

On Fri, Jul 9, 2010 at 2:51 AM, Georg Brandl  wrote:
> Yes, but[tm] it is not always easy to find the correct module to look for
> __docformat__ when given an object.

True.  That PEP was written before decorators were common, in
particular.  That's changed the landscape in substantial ways.

It may be that at this point, there's no good way to deal with
formatting in docstrings at anything other than the project level,
where policies for the code can be set if desired.

Ideally, the format of a docstring would be captured along with the
docstring itself.


  -Fred

-- 
Fred L. Drake, Jr.
"A storm broke loose in my mind."  --Albert Einstein
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Martin Geisler]

Georg Brandl  writes:

> Am 08.07.2010 17:44, schrieb Martin Geisler:
>> Steve Holden  writes:
>> 
>>> Martin Geisler wrote:
 "Stephen J. Turnbull"  writes:
 
> Just ask Martin, there are too many possibilities here to worry
> about. If maybe we want it, and he is willing to contribute the
> parts he wrote to Python under Python's license, then we can worry
> about whether we really want it and about how much any required
> hoop-jumping will cost.
 
 I would be happy to relicense it under the Python license.
>>>
>>> I believe the ideal outcome, if it is possible, is for you to sign a
>>> contributor agreement. This will license your material to the PSF in
>>> such a way that we can release it under whatever license we deem
>>> necessary.
>> 
>> Sure, I'll be happy to sign a contributor agreement if you guys think it
>> worthwhile to use my little parser and formatter.
>
> Problem is, in the case of help() we have no way of knowing whether the
> given __doc__ string is supposed to be (mini)reST.  Of course, reverting
> to showing the plain content on parsing errors is one possibility, but
> I can still imagine instances where something is successfully interpreted
> as reST, but intended to be read and understood verbatim by the author.

The minirst module is actually designed to never fail: the text is first
divided into paragraphs, and the paragraphs are then looked at one by
one to see if they look like something more specific like a list.

> It's different for Hg, of course, there you can just decide that help
> texts have to be reST.

Right, good point. At first I figured that you could also "just" convert
the docstrings in Python, but since the help builtin is used on lots of
code outside of Python this isn't really enough.

-- 
Martin Geisler

aragost Trifork -- Professional Mercurial support
http://aragost.com/mercurial/

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Georg Brandl]

Am 09.07.2010 00:01, schrieb Fred Drake:
> On Thu, Jul 8, 2010 at 5:42 PM, Alexander Belopolsky
>  wrote:
>> I am against mark-up in doc-strings, but this problem can be easily
>> solved by placing a magic character at __doc__[0] to indicate that the
>> rest is  (mini)reST.

Ugh. :)

> Or __docformat__ can be set appropriately.  See:
> 
> http://www.python.org/dev/peps/pep-0258/#id42

Yes, but[tm] it is not always easy to find the correct module to look for
__docformat__ when given an object.

Georg

-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Stephen J. Turnbull]

Steve Holden writes:

 > That is _so_ Python 2 ;-)

High praise!
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Steve Holden]

Fred Drake wrote:
> On Thu, Jul 8, 2010 at 5:42 PM, Alexander Belopolsky
>  wrote:
>> I am against mark-up in doc-strings, but this problem can be easily
>> solved by placing a magic character at __doc__[0] to indicate that the
>> rest is  (mini)reST.
> 
> Or __docformat__ can be set appropriately.  See:
> 
> http://www.python.org/dev/peps/pep-0258/#id42
> 
That is _so_ Python 2 ;-)

regards
 Steve
-- 
Steve Holden   +1 571 484 6266   +1 800 494 3119
DjangoCon US September 7-9, 2010http://djangocon.us/
See Python Video!   http://python.mirocommunity.org/
Holden Web LLC http://www.holdenweb.com/

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Fred Drake]

On Thu, Jul 8, 2010 at 5:42 PM, Alexander Belopolsky
 wrote:
> I am against mark-up in doc-strings, but this problem can be easily
> solved by placing a magic character at __doc__[0] to indicate that the
> rest is  (mini)reST.

Or __docformat__ can be set appropriately.  See:

http://www.python.org/dev/peps/pep-0258/#id42


  -Fred

-- 
Fred L. Drake, Jr.
"A storm broke loose in my mind."  --Albert Einstein
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Alexander Belopolsky]

On Thu, Jul 8, 2010 at 5:21 PM, Georg Brandl  wrote:
..
> Problem is, in the case of help() we have no way of knowing whether the
> given __doc__ string is supposed to be (mini)reST.

I am against mark-up in doc-strings, but this problem can be easily
solved by placing a magic character at __doc__[0] to indicate that the
rest is  (mini)reST.  The magic character should be chosen to be
inconspicuous and unlikely to appear at the start of a plain-text
docstting.  For example, any type closing braces, ), }. ] will do, or
any end of sentence punctuation such as . or !.
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Fred Drake]

On Thu, Jul 8, 2010 at 5:21 PM, Georg Brandl  wrote:
> Problem is, in the case of help() we have no way of knowing whether the
> given __doc__ string is supposed to be (mini)reST.  Of course, reverting
> to showing the plain content on parsing errors is one possibility, but
> I can still imagine instances where something is successfully interpreted
> as reST, but intended to be read and understood verbatim by the author.

The docstring processing PEP provides for this:

http://www.python.org/dev/peps/pep-0258/#id42


  -Fred

-- 
Fred L. Drake, Jr.
"A storm broke loose in my mind."  --Albert Einstein
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Georg Brandl]

Am 08.07.2010 17:44, schrieb Martin Geisler:
> Steve Holden  writes:
> 
>> Martin Geisler wrote:
>>> "Stephen J. Turnbull"  writes:
>>> 
 Just ask Martin, there are too many possibilities here to worry
 about. If maybe we want it, and he is willing to contribute the
 parts he wrote to Python under Python's license, then we can worry
 about whether we really want it and about how much any required
 hoop-jumping will cost.
>>> 
>>> I would be happy to relicense it under the Python license.
>>
>> I believe the ideal outcome, if it is possible, is for you to sign a
>> contributor agreement. This will license your material to the PSF in
>> such a way that we can release it under whatever license we deem
>> necessary.
> 
> Sure, I'll be happy to sign a contributor agreement if you guys think it
> worthwhile to use my little parser and formatter.

Problem is, in the case of help() we have no way of knowing whether the
given __doc__ string is supposed to be (mini)reST.  Of course, reverting
to showing the plain content on parsing errors is one possibility, but
I can still imagine instances where something is successfully interpreted
as reST, but intended to be read and understood verbatim by the author.

It's different for Hg, of course, there you can just decide that help
texts have to be reST.

Georg


-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Martin Geisler]

Steve Holden  writes:

> Martin Geisler wrote:
>> "Stephen J. Turnbull"  writes:
>> 
>>> Just ask Martin, there are too many possibilities here to worry
>>> about. If maybe we want it, and he is willing to contribute the
>>> parts he wrote to Python under Python's license, then we can worry
>>> about whether we really want it and about how much any required
>>> hoop-jumping will cost.
>> 
>> I would be happy to relicense it under the Python license.
>
> I believe the ideal outcome, if it is possible, is for you to sign a
> contributor agreement. This will license your material to the PSF in
> such a way that we can release it under whatever license we deem
> necessary.

Sure, I'll be happy to sign a contributor agreement if you guys think it
worthwhile to use my little parser and formatter.

-- 
Martin Geisler

aragost Trifork -- Professional Mercurial support
http://aragost.com/mercurial/

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Steve Holden]

Martin Geisler wrote:
> "Stephen J. Turnbull"  writes:
> 
>> Benjamin Peterson writes:
>>  > 2010/7/7 Stephen J. Turnbull :
>>  > > Antoine Pitrou writes:
>>  > >
>>  > >  > >   http://selenic.com/hg/file/tip/mercurial/minirst.py
>>  > >  >
>>  > >  > Given that Mercurial is GPL, this is probably of no use to us,
>>  > >  > unfortunately.
> 
> I must admit that reading this felt strange somehow... that a piece of
> open source code should be useless. But I understand what you mean :)
> 
>>  > > Given that Martin apparently is the only or main author, I don't
>>  > > see a problem as long as he's willing.
>>  > 
>>  > And he hasn't assigned the copyright away.
>>
>> (Or that the assignment has an automatic author-use-ok clause like the
>> standard FSF assignment does, etc.)
> 
> We don't assign copyright in Mercurial, so this should be no problem.
> This also meant that we had to contact about 300 guys when changing from
> GPLv2 to GPLv2+.
> 
>> Just ask Martin, there are too many possibilities here to worry about.
>> If maybe we want it, and he is willing to contribute the parts he
>> wrote to Python under Python's license, then we can worry about
>> whether we really want it and about how much any required hoop-jumping
>> will cost.
> 
> I would be happy to relicense it under the Python license.
> 

I believe the ideal outcome, if it is possible, is for you to sign a
contributor agreement. This will license your material to the PSF in
such a way that we can release it under whatever license we deem necessary.

regards
 Steve
-- 
Steve Holden   +1 571 484 6266   +1 800 494 3119
DjangoCon US September 7-9, 2010http://djangocon.us/
See Python Video!   http://python.mirocommunity.org/
Holden Web LLC http://www.holdenweb.com/
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Martin Geisler]

"Stephen J. Turnbull"  writes:

> Benjamin Peterson writes:
>  > 2010/7/7 Stephen J. Turnbull :
>  > > Antoine Pitrou writes:
>  > >
>  > >  > >   http://selenic.com/hg/file/tip/mercurial/minirst.py
>  > >  >
>  > >  > Given that Mercurial is GPL, this is probably of no use to us,
>  > >  > unfortunately.

I must admit that reading this felt strange somehow... that a piece of
open source code should be useless. But I understand what you mean :)

>  > > Given that Martin apparently is the only or main author, I don't
>  > > see a problem as long as he's willing.
>  > 
>  > And he hasn't assigned the copyright away.
>
> (Or that the assignment has an automatic author-use-ok clause like the
> standard FSF assignment does, etc.)

We don't assign copyright in Mercurial, so this should be no problem.
This also meant that we had to contact about 300 guys when changing from
GPLv2 to GPLv2+.

> Just ask Martin, there are too many possibilities here to worry about.
> If maybe we want it, and he is willing to contribute the parts he
> wrote to Python under Python's license, then we can worry about
> whether we really want it and about how much any required hoop-jumping
> will cost.

I would be happy to relicense it under the Python license.

-- 
Martin Geisler

aragost Trifork: Professional Mercurial support
http://aragost.com/mercurial/

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Stephen J. Turnbull]

Benjamin Peterson writes:
 > 2010/7/7 Stephen J. Turnbull :
 > > Antoine Pitrou writes:
 > >
 > >  > >   http://selenic.com/hg/file/tip/mercurial/minirst.py
 > >  >
 > >  > Given that Mercurial is GPL, this is probably of no use to us,
 > >  > unfortunately.
 > >
 > > Given that Martin apparently is the only or main author, I don't see a
 > > problem as long as he's willing.
 > 
 > And he hasn't assigned the copyright away.

(Or that the assignment has an automatic author-use-ok clause like the
standard FSF assignment does, etc.)

Just ask Martin, there are too many possibilities here to worry about.
If maybe we want it, and he is willing to contribute the parts he
wrote to Python under Python's license, then we can worry about
whether we really want it and about how much any required hoop-jumping
will cost.
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Benjamin Peterson]

2010/7/7 Stephen J. Turnbull :
> Antoine Pitrou writes:
>
>  > >   http://selenic.com/hg/file/tip/mercurial/minirst.py
>  >
>  > Given that Mercurial is GPL, this is probably of no use to us,
>  > unfortunately.
>
> Given that Martin apparently is the only or main author, I don't see a
> problem as long as he's willing.

And he hasn't assigned the copyright away.


-- 
Regards,
Benjamin
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Stephen J. Turnbull]

Antoine Pitrou writes:

 > >   http://selenic.com/hg/file/tip/mercurial/minirst.py
 > 
 > Given that Mercurial is GPL, this is probably of no use to us,
 > unfortunately.

Given that Martin apparently is the only or main author, I don't see a
problem as long as he's willing.

Martin?
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Fred Drake]

On Wed, Jul 7, 2010 at 4:58 PM, Georg Brandl  wrote:
> Let's say we were okay with giving up single-source docs,

It's not clear that this is a goal.

> one potential
> problem is that autodoc needs to import the modules in question, which
> can become a problem, on one hand for platform-specific modules, on the
> other because the Python building the docs is not necessarily the Python
> that is documented.

This is an excellent point.  I'm less worried about the
platform-specific issues, since we can decide that those in particular
can't use the auto* support, but the need to build docs for different
versions/implementations of Python is an interesting use case.


  -Fred

-- 
Fred L. Drake, Jr.
"A storm broke loose in my mind."  --Albert Einstein
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Michael Foord]

On 07/07/2010 21:54, Georg Brandl wrote:

Am 07.07.2010 20:12, schrieb Barry Warsaw:
   

On Jul 07, 2010, at 07:30 PM, Georg Brandl wrote:

 

Overall, I think that we can make stdlib docstrings valid reST -- even
if it's reST without much markup -- but valid, so that people pulling
in stdlib doc- strings into Sphinx docs won't get ugly warnings.

What I would *not* like to see is heavy markup and Sphinx specifics --
that would only make sense if we included the docstrings in the docs,
and I don't see that coming.
   

Does it make sense to add (reST-style) epydoc markup for API signatures?
E.g.

def create_foo(name, parent=None):
 """Create the named foo.

 The named foo must not already exist, but if optional `parent` is given,
 it must exist.

 :param name: The name of the new foo.
 :type name: string
 :param parent: The new foo's parent.  If given, this must exist.
 :type parent: string
 :return: The new foo.
 :rtype: `Foo`
 :raises BadFooNameError: when `name` is illegal.
 :raises FooAlreadyExistsError: when a foo with `name` already exists.
 :raises BadParentError: when the foo's parent does not exist.
 """

We could then generate automatic API docs from this, a la:

http://www.blender.org/documentation/248PythonDoc/
 

Yes, but: do we want this?

   


-1 :-)

I find those epydoc style framed API docs very hard to read and 
navigate. On the other hand autogenerated API docs *can* be good looking 
and usable.


Michael


Georg

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.uk
   



--
http://www.ironpythoninaction.com/
http://www.voidspace.org.uk/blog

READ CAREFULLY. By accepting and reading this email you agree, on behalf of 
your employer, to release me from all obligations and waivers arising from any 
and all NON-NEGOTIATED agreements, licenses, terms-of-service, shrinkwrap, 
clickwrap, browsewrap, confidentiality, non-disclosure, non-compete and 
acceptable use policies (”BOGUS AGREEMENTS”) that I have entered into with your 
employer, its partners, licensors, agents and assigns, in perpetuity, without 
prejudice to my ongoing rights and privileges. You further represent that you 
have the authority to release me from any BOGUS AGREEMENTS on behalf of your 
employer.


___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Antoine Pitrou]

On Wed, 07 Jul 2010 22:58:47 +0200
Martin Geisler  wrote:

> "C. Titus Brown"  writes:
> 
> > I guess docutils isn't in the stdlib (should it be?) or else we could
> > modify 'help' to use it to prepare a straight text formatting.
> 
> We're using light-weight ReST markup in the Mercurial help texts and
> transform it into straight text upon display in the terminal.
> 
> We want no external dependencies for Mercurial, so I wrote a "mini ReST"
> parser in about 400 lines of code. It cheats a lot and can only handle
> simple constructs... but maybe it would be interesting for Python's
> help? You find it here:
> 
>   http://selenic.com/hg/file/tip/mercurial/minirst.py

Given that Mercurial is GPL, this is probably of no use to us,
unfortunately.

Regards

Antoine.


___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Georg Brandl]

Am 07.07.2010 21:52, schrieb Brett Cannon:
> On Wed, Jul 7, 2010 at 10:30, Georg Brandl  wrote:
>> Am 07.07.2010 18:09, schrieb Michael Foord:
 Hi all,

 over on the fellowship o' the packaging mailing list, one of our GSoC 
 students
 (merwok) asked about how much formatting info should go into Python 
 stdlib
 docstrings.  Right now the stdlib docstrings are primarily text, 
 AFAIK; but
 with the switch to Sphinx for the official Python docs, should we 
 permit
 ReST-general and/or Sphinx-specific markup in docstrings?
>>
>> I promised to write a PEP about that some time in the future.  (Probably 
>> after
>> 3.2 final.)
> 
> For those of you who aren't aware, there actually already is a PEP on
> using reST in docstrings: http://python.org/dev/peps/pep-0287/ .
> 
> But it could stand to be updated by Georg with current practice with
> our internal doc practices as 2002 was back when we were still using
> LaTeX.

Thanks for the reference, Brett.  I do not intend to do my work in PEP 287
(though it probably could be given a few updates, have to look in detail),
but rather refer to it in the new one, since my proposed PEP was less about
actual syntax of reST docstrings than about their use in the standard
library.  As far as I could see, most recommendations from PEP 287 would
apply to them.

Georg

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Georg Brandl]

Am 07.07.2010 21:11, schrieb Fred Drake:
> On Wed, Jul 7, 2010 at 2:27 PM, Georg Brandl  wrote:
>> I know, and this is what I originally intended for Sphinx.  However, the 
>> calls
>> for automatic doc generation are very loud, and it's understandable that most
>> project can't afford writing their documentation twice.
> 
> The ability to provide extended content beyond what's provided in the
> docstring using the auto* constructs may make it feasible to start
> avoiding some of those DRY violations for Python's standard library;
> I'm enjoying those for another project.
> 
> I hope we don't end up in a position where we can't use the auto*
> constructs in the Python documentation.

Let's say we were okay with giving up single-source docs, one potential
problem is that autodoc needs to import the modules in question, which
can become a problem, on one hand for platform-specific modules, on the
other because the Python building the docs is not necessarily the Python
that is documented.

Georg

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Martin Geisler]

"C. Titus Brown"  writes:

> I guess docutils isn't in the stdlib (should it be?) or else we could
> modify 'help' to use it to prepare a straight text formatting.

We're using light-weight ReST markup in the Mercurial help texts and
transform it into straight text upon display in the terminal.

We want no external dependencies for Mercurial, so I wrote a "mini ReST"
parser in about 400 lines of code. It cheats a lot and can only handle
simple constructs... but maybe it would be interesting for Python's
help? You find it here:

  http://selenic.com/hg/file/tip/mercurial/minirst.py

Its test and the corresponding output shows the markup it can parse:

  http://selenic.com/hg/file/tip/tests/test-minirst.py
  http://selenic.com/hg/file/tip/tests/test-minirst.py.out

It would of course be much nicer to have Docutils in the standard
library. I'm not a Docutils developer, but to me it seems that Docutils
is now a very stable and widely used package, so it would IMHO make
sense to include it.

-- 
Martin Geisler

Mercurial links: http://mercurial.ch/


pgpf0R31gMZHO.pgp
Description: PGP signature
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Georg Brandl]

Am 07.07.2010 20:12, schrieb Barry Warsaw:
> On Jul 07, 2010, at 07:30 PM, Georg Brandl wrote:
> 
>>Overall, I think that we can make stdlib docstrings valid reST -- even
>>if it's reST without much markup -- but valid, so that people pulling
>>in stdlib doc- strings into Sphinx docs won't get ugly warnings.
>>
>>What I would *not* like to see is heavy markup and Sphinx specifics --
>>that would only make sense if we included the docstrings in the docs,
>>and I don't see that coming.
> 
> Does it make sense to add (reST-style) epydoc markup for API signatures?
> E.g.
> 
> def create_foo(name, parent=None):
> """Create the named foo.
> 
> The named foo must not already exist, but if optional `parent` is given,
> it must exist.
> 
> :param name: The name of the new foo.
> :type name: string
> :param parent: The new foo's parent.  If given, this must exist.
> :type parent: string
> :return: The new foo.
> :rtype: `Foo`
> :raises BadFooNameError: when `name` is illegal.
> :raises FooAlreadyExistsError: when a foo with `name` already exists.
> :raises BadParentError: when the foo's parent does not exist.
> """
> 
> We could then generate automatic API docs from this, a la:
> 
> http://www.blender.org/documentation/248PythonDoc/

Yes, but: do we want this?

Georg

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Brett Cannon]

On Wed, Jul 7, 2010 at 10:30, Georg Brandl  wrote:
> Am 07.07.2010 18:09, schrieb Michael Foord:
>>>     Hi all,
>>>
>>>     over on the fellowship o' the packaging mailing list, one of our GSoC 
>>> students
>>>     (merwok) asked about how much formatting info should go into Python 
>>> stdlib
>>>     docstrings.  Right now the stdlib docstrings are primarily text, AFAIK; 
>>> but
>>>     with the switch to Sphinx for the official Python docs, should we permit
>>>     ReST-general and/or Sphinx-specific markup in docstrings?
>
> I promised to write a PEP about that some time in the future.  (Probably after
> 3.2 final.)

For those of you who aren't aware, there actually already is a PEP on
using reST in docstrings: http://python.org/dev/peps/pep-0287/ .

But it could stand to be updated by Georg with current practice with
our internal doc practices as 2002 was back when we were still using
LaTeX.

-Brett

>
>>>     Hmm, I don't actually see that the stdlib docstrings are imported into 
>>> the
>>>     Python documentation anywhere, so maybe the use of Sphinx isn't that
>>>     relevant.  But how about ReST in general?
>>>
>>>
>>> So will we be able to use .__docs__ within python interpretor, which is 
>>> quite
>>> handy feature.
>>> >>> print(os.getcwd.__doc__)
>>> getcwd() -> path
>>>
>>> Return a string representing the current working directory.
>>> Also some python interpretors like bpython uses it ; a snapshot here -
>>>  http://cl.ly/c5bb3be4a01d9d44732f
>>> So will it be ok to break them ?
>>
>> Using ReST won't *break* these tools, but may make the output less readable.
>>
>> I would say that the major use of docstrings is for interactive help - so
>> interactive readability should be *the most important* (but perhaps not only)
>> factor when considering how to format standard library docstrings.
>
> Agreed.  However, reST doesn't need to be less readable if the specific
> inline markup is not used.  For example, using `identifier` to refer to a
> function or *var* to refer to a variable (which is already done at quite a
> few places) is very readable IMO.  Using ``code`` also isn't bad, considering
> that double quotes are not much different and potentially ambiguous.
>
> Overall, I think that we can make stdlib docstrings valid reST -- even if it's
> reST without much markup -- but valid, so that people pulling in stdlib doc-
> strings into Sphinx docs won't get ugly warnings.
>
> What I would *not* like to see is heavy markup and Sphinx specifics -- that
> would only make sense if we included the docstrings in the docs, and I don't
> see that coming.
>
> cheers,
> Georg
>
> ___
> Python-Dev mailing list
> Python-Dev@python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: 
> http://mail.python.org/mailman/options/python-dev/brett%40python.org
>
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Brett Cannon]

On Wed, Jul 7, 2010 at 11:46, Antoine Pitrou  wrote:
> On Wed, 7 Jul 2010 14:12:17 -0400
> Barry Warsaw  wrote:
>> On Jul 07, 2010, at 07:30 PM, Georg Brandl wrote:
>>
>> >Overall, I think that we can make stdlib docstrings valid reST -- even
>> >if it's reST without much markup -- but valid, so that people pulling
>> >in stdlib doc- strings into Sphinx docs won't get ugly warnings.
>> >
>> >What I would *not* like to see is heavy markup and Sphinx specifics --
>> >that would only make sense if we included the docstrings in the docs,
>> >and I don't see that coming.
>>
>> Does it make sense to add (reST-style) epydoc markup for API signatures?
>> E.g.
>
> It really looks ugly (and annoying to decipher) when viewed in plain
> text.

I agree. And it is highly repetitive since the signature information
is right there already. All of that info in those annotations can
easily be written in paragraph form if needed and honestly would read
better to my eyes.

-Brett

>
> Regards
>
> Antoine.
>
>
>>
>> def create_foo(name, parent=None):
>>     """Create the named foo.
>>
>>     The named foo must not already exist, but if optional `parent` is given,
>>     it must exist.
>>
>>     :param name: The name of the new foo.
>>     :type name: string
>>     :param parent: The new foo's parent.  If given, this must exist.
>>     :type parent: string
>>     :return: The new foo.
>>     :rtype: `Foo`
>>     :raises BadFooNameError: when `name` is illegal.
>>     :raises FooAlreadyExistsError: when a foo with `name` already exists.
>>     :raises BadParentError: when the foo's parent does not exist.
>>     """
>>
>> We could then generate automatic API docs from this, a la:
>>
>> http://www.blender.org/documentation/248PythonDoc/
>>
>> -Barry
>>
>
>
> ___
> Python-Dev mailing list
> Python-Dev@python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: 
> http://mail.python.org/mailman/options/python-dev/brett%40python.org
>
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Fred Drake]

On Wed, Jul 7, 2010 at 2:27 PM, Georg Brandl  wrote:
> I know, and this is what I originally intended for Sphinx.  However, the calls
> for automatic doc generation are very loud, and it's understandable that most
> project can't afford writing their documentation twice.

The ability to provide extended content beyond what's provided in the
docstring using the auto* constructs may make it feasible to start
avoiding some of those DRY violations for Python's standard library;
I'm enjoying those for another project.

I hope we don't end up in a position where we can't use the auto*
constructs in the Python documentation.


  -Fred

-- 
Fred L. Drake, Jr.
"A storm broke loose in my mind."  --Albert Einstein
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Antoine Pitrou]

On Wed, 7 Jul 2010 14:12:17 -0400
Barry Warsaw  wrote:
> On Jul 07, 2010, at 07:30 PM, Georg Brandl wrote:
> 
> >Overall, I think that we can make stdlib docstrings valid reST -- even
> >if it's reST without much markup -- but valid, so that people pulling
> >in stdlib doc- strings into Sphinx docs won't get ugly warnings.
> >
> >What I would *not* like to see is heavy markup and Sphinx specifics --
> >that would only make sense if we included the docstrings in the docs,
> >and I don't see that coming.
> 
> Does it make sense to add (reST-style) epydoc markup for API signatures?
> E.g.

It really looks ugly (and annoying to decipher) when viewed in plain
text.

Regards

Antoine.


> 
> def create_foo(name, parent=None):
> """Create the named foo.
> 
> The named foo must not already exist, but if optional `parent` is given,
> it must exist.
> 
> :param name: The name of the new foo.
> :type name: string
> :param parent: The new foo's parent.  If given, this must exist.
> :type parent: string
> :return: The new foo.
> :rtype: `Foo`
> :raises BadFooNameError: when `name` is illegal.
> :raises FooAlreadyExistsError: when a foo with `name` already exists.
> :raises BadParentError: when the foo's parent does not exist.
> """
> 
> We could then generate automatic API docs from this, a la:
> 
> http://www.blender.org/documentation/248PythonDoc/
> 
> -Barry
> 


___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Alexander Belopolsky]

On Wed, Jul 7, 2010 at 2:12 PM, Barry Warsaw  wrote:
..
> Does it make sense to add (reST-style) epydoc markup for API signatures?
> E.g.
>
> def create_foo(name, parent=None):
>    """Create the named foo.
>
>    The named foo must not already exist, but if optional `parent` is given,
>    it must exist.
>
>    :param name: The name of the new foo.
>    :type name: string
..

-1.  Repeating the function signature in the docstring only adds
clutter and Java-style formal types/exceptions specifications are
rarely appropriate in Python.  I think marking arguments up with * as
in *name*, *parent*, should be enough in most cases.
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Georg Brandl]

Am 07.07.2010 19:53, schrieb Éric Araujo:
>> I promised to write a PEP about that some time in the future.  (Probably 
>> after
>> 3.2 final.)
> 
> Nice.
> 
> It seems that projects putting Sphinxy reST in their doc are using
> automatic doc generation. This is however not always the best way to
> make good doc, as demonstrated by Python’s hand-written,
> very-high-quality documentation.

I know, and this is what I originally intended for Sphinx.  However, the calls
for automatic doc generation are very loud, and it's understandable that most
project can't afford writing their documentation twice.

>> Agreed.  However, reST doesn't need to be less readable if the specific
>> inline markup is not used.  For example, using `identifier` to refer to a
>> function or *var* to refer to a variable (which is already done at quite a
>> few places) is very readable IMO.  Using ``code`` also isn't bad, considering
>> that double quotes are not much different and potentially ambiguous.
>> 
>> Overall, I think that we can make stdlib docstrings valid reST -- even if 
>> it's
>> reST without much markup -- but valid, so that people pulling in stdlib doc-
>> strings into Sphinx docs won't get ugly warnings.
>> 
>> What I would *not* like to see is heavy markup and Sphinx specifics -- that
>> would only make sense if we included the docstrings in the docs, and I don't
>> see that coming.
> 
> Clear answer, thanks! We have backported some modules in distutils2, and
> some docstrings already contain Sphinxy reST (e.g. :param: and :pep:),
> it’s good to know now that we shouldn’t put hours into that to see it
> reverted later.

:pep: isn't Sphinxy, put provided by docutils, and the :param foo: field
lists are also valid reST, if rendered a bit awkwardly without the transforms
that Sphinx does to display them in epydoc style.

cheers,
Georg

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Robert Kern]

On 7/7/10 1:53 PM, Éric Araujo wrote:

I promised to write a PEP about that some time in the future.  (Probably after
3.2 final.)


Nice.

It seems that projects putting Sphinxy reST in their doc are using
automatic doc generation. This is however not always the best way to
make good doc, as demonstrated by Python’s hand-written,
very-high-quality documentation.


This is a false dichotomy. Many of those projects using Sphinxy reST in their 
docstrings are using the semi-automatic[1] doc generation provided by Sphinx to 
construct *part* of their documentation. Namely, the reference of functions, 
classes and methods. A large part of Python's library reference consists of 
exactly this. Having a function's docstring provide the content for its entry in 
the library reference has the substantial DRY benefit of having exactly one 
source for the comprehensive documentation of that function available from both 
help() and the manual. As someone who uses the interactive prompt to play with 
things and read docstrings intensively, I would really like to see docstrings 
providing the same information as the manual.


Of course, opinions differ about how comprehensive docstrings should be compared 
to the reference manual's entries. And there are technical reasons for not 
wanting to try to extract docstrings from code (e.g. platform-specific modules). 
But one should not fear that the quality of the manual would decline.


[1] That's the really nice thing about Sphinx's docstring extraction features in 
contrast with other such tools. It doesn't generate a manual from the 
docstrings; it makes you explicitly reference the docstrings into the manual's 
text. This would fit in very naturally with Python's library reference.


--
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
 that is made terrible by our own mad attempt to interpret it as though it had
 an underlying truth."
  -- Umberto Eco

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Barry Warsaw]

On Jul 07, 2010, at 07:30 PM, Georg Brandl wrote:

>Overall, I think that we can make stdlib docstrings valid reST -- even
>if it's reST without much markup -- but valid, so that people pulling
>in stdlib doc- strings into Sphinx docs won't get ugly warnings.
>
>What I would *not* like to see is heavy markup and Sphinx specifics --
>that would only make sense if we included the docstrings in the docs,
>and I don't see that coming.

Does it make sense to add (reST-style) epydoc markup for API signatures?
E.g.

def create_foo(name, parent=None):
"""Create the named foo.

The named foo must not already exist, but if optional `parent` is given,
it must exist.

:param name: The name of the new foo.
:type name: string
:param parent: The new foo's parent.  If given, this must exist.
:type parent: string
:return: The new foo.
:rtype: `Foo`
:raises BadFooNameError: when `name` is illegal.
:raises FooAlreadyExistsError: when a foo with `name` already exists.
:raises BadParentError: when the foo's parent does not exist.
"""

We could then generate automatic API docs from this, a la:

http://www.blender.org/documentation/248PythonDoc/

-Barry


signature.asc
Description: PGP signature
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Éric Araujo]

> I promised to write a PEP about that some time in the future.  (Probably after
> 3.2 final.)

Nice.

It seems that projects putting Sphinxy reST in their doc are using
automatic doc generation. This is however not always the best way to
make good doc, as demonstrated by Python’s hand-written,
very-high-quality documentation.

> Agreed.  However, reST doesn't need to be less readable if the specific
> inline markup is not used.  For example, using `identifier` to refer to a
> function or *var* to refer to a variable (which is already done at quite a
> few places) is very readable IMO.  Using ``code`` also isn't bad, considering
> that double quotes are not much different and potentially ambiguous.
> 
> Overall, I think that we can make stdlib docstrings valid reST -- even if it's
> reST without much markup -- but valid, so that people pulling in stdlib doc-
> strings into Sphinx docs won't get ugly warnings.
> 
> What I would *not* like to see is heavy markup and Sphinx specifics -- that
> would only make sense if we included the docstrings in the docs, and I don't
> see that coming.

Clear answer, thanks! We have backported some modules in distutils2, and
some docstrings already contain Sphinxy reST (e.g. :param: and :pep:),
it’s good to know now that we shouldn’t put hours into that to see it
reverted later.

Regards

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Senthil Kumaran]

On Wed, Jul 7, 2010 at 11:00 PM, Georg Brandl  wrote:
> Agreed.  However, reST doesn't need to be less readable if the specific
> inline markup is not used.  For example, using `identifier` to refer to a
> function or *var* to refer to a variable (which is already done at quite a
> few places) is very readable IMO.  Using ``code`` also isn't bad, considering
> that double quotes are not much different and potentially ambiguous.

What are the specific advantages that you see?
Can it more useful in some cases than the other?



-- 
Senthil
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Georg Brandl]

Am 07.07.2010 18:09, schrieb Michael Foord:
>> Hi all,
>>
>> over on the fellowship o' the packaging mailing list, one of our GSoC 
>> students
>> (merwok) asked about how much formatting info should go into Python 
>> stdlib
>> docstrings.  Right now the stdlib docstrings are primarily text, AFAIK; 
>> but
>> with the switch to Sphinx for the official Python docs, should we permit
>> ReST-general and/or Sphinx-specific markup in docstrings?

I promised to write a PEP about that some time in the future.  (Probably after
3.2 final.)

>> Hmm, I don't actually see that the stdlib docstrings are imported into 
>> the
>> Python documentation anywhere, so maybe the use of Sphinx isn't that
>> relevant.  But how about ReST in general?
>>
>>
>> So will we be able to use .__docs__ within python interpretor, which is quite
>> handy feature.
>> >>> print(os.getcwd.__doc__)
>> getcwd() -> path
>>
>> Return a string representing the current working directory.
>> Also some python interpretors like bpython uses it ; a snapshot here -
>>  http://cl.ly/c5bb3be4a01d9d44732f
>> So will it be ok to break them ?
> 
> Using ReST won't *break* these tools, but may make the output less readable.
> 
> I would say that the major use of docstrings is for interactive help - so
> interactive readability should be *the most important* (but perhaps not only)
> factor when considering how to format standard library docstrings.

Agreed.  However, reST doesn't need to be less readable if the specific
inline markup is not used.  For example, using `identifier` to refer to a
function or *var* to refer to a variable (which is already done at quite a
few places) is very readable IMO.  Using ``code`` also isn't bad, considering
that double quotes are not much different and potentially ambiguous.

Overall, I think that we can make stdlib docstrings valid reST -- even if it's
reST without much markup -- but valid, so that people pulling in stdlib doc-
strings into Sphinx docs won't get ugly warnings.

What I would *not* like to see is heavy markup and Sphinx specifics -- that
would only make sense if we included the docstrings in the docs, and I don't
see that coming.

cheers,
Georg

___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Shashwat Anand]

On Wed, Jul 7, 2010 at 9:39 PM, Michael Foord wrote:

>  On 07/07/2010 17:06, Shashwat Anand wrote:
>
>
>
> On Wed, Jul 7, 2010 at 9:24 PM, C. Titus Brown  wrote:
>
>> Hi all,
>>
>> over on the fellowship o' the packaging mailing list, one of our GSoC
>> students
>> (merwok) asked about how much formatting info should go into Python stdlib
>> docstrings.  Right now the stdlib docstrings are primarily text, AFAIK;
>> but
>> with the switch to Sphinx for the official Python docs, should we permit
>> ReST-general and/or Sphinx-specific markup in docstrings?
>>
>> Hmm, I don't actually see that the stdlib docstrings are imported into the
>> Python documentation anywhere, so maybe the use of Sphinx isn't that
>> relevant.  But how about ReST in general?
>>
>
>  So will we be able to use .__docs__ within python interpretor, which is
> quite handy feature.
> >>> print(os.getcwd.__doc__)
> getcwd() -> path
>
>  Return a string representing the current working directory.
> Also some python interpretors like bpython uses it ; a snapshot here -  h
> ttp://cl.ly/c5bb3be4a01d9d44732f
> So will it be ok to break them ?
>
>
> Using ReST won't *break* these tools, but may make the output less
> readable.
>

Oops. Sorry for the wrong choice of word. I meant the 'output will be less
readable', text are perhaps easier to read than ReST, thats what I meant.

>
> I would say that the major use of docstrings is for interactive help - so
> interactive readability should be *the most important* (but perhaps not
> only) factor when considering how to format standard library docstrings.
>
> Michael
>
>
>
>>
>> See
>>
>>http://sphinx.pocoo.org/markup/index.html
>>
>> for sphinx-specific markup constructs.
>>
>> thanks,
>> --titus
>> --
>> C. Titus Brown, c...@msu.edu
>>
>>
>
> ___
> Python-Dev mailing list
> python-...@python.orghttp://mail.python.org/mailman/listinfo/python-dev
>
> Unsubscribe: 
> http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.uk
>
>
>
> -- http://www.ironpythoninaction.com/http://www.voidspace.org.uk/blog
>
> READ CAREFULLY. By accepting and reading this email you agree, on behalf of 
> your employer, to release me from all obligations and waivers arising from 
> any and all NON-NEGOTIATED agreements, licenses, terms-of-service, 
> shrinkwrap, clickwrap, browsewrap, confidentiality, non-disclosure, 
> non-compete and acceptable use policies (”BOGUS AGREEMENTS”) that I have 
> entered into with your employer, its partners, licensors, agents and assigns, 
> in perpetuity, without prejudice to my ongoing rights and privileges. You 
> further represent that you have the authority to release me from any BOGUS 
> AGREEMENTS on behalf of your employer.
>
>
>
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[C. Titus Brown]

On Wed, Jul 07, 2010 at 05:09:40PM +0100, Michael Foord wrote:
> On 07/07/2010 17:06, Shashwat Anand wrote:
>> On Wed, Jul 7, 2010 at 9:24 PM, C. Titus Brown > > wrote:
>>
>> Hi all,
>>
>> over on the fellowship o' the packaging mailing list, one of our
>> GSoC students
>> (merwok) asked about how much formatting info should go into
>> Python stdlib
>> docstrings.  Right now the stdlib docstrings are primarily text,
>> AFAIK; but
>> with the switch to Sphinx for the official Python docs, should we
>> permit
>> ReST-general and/or Sphinx-specific markup in docstrings?
>>
>> Hmm, I don't actually see that the stdlib docstrings are imported
>> into the
>> Python documentation anywhere, so maybe the use of Sphinx isn't that
>> relevant.  But how about ReST in general?
>>
>>
>> So will we be able to use .__docs__ within python interpretor, which  
>> is quite handy feature.
>> >>> print(os.getcwd.__doc__)
>> getcwd() -> path
>>
>> Return a string representing the current working directory.
>> Also some python interpretors like bpython uses it ; a snapshot here -  
>>  http://cl.ly/c5bb3be4a01d9d44732f
>> So will it be ok to break them ?
>
> Using ReST won't *break* these tools, but may make the output less  
> readable.
>
> I would say that the major use of docstrings is for interactive help -  
> so interactive readability should be *the most important* (but perhaps  
> not only) factor when considering how to format standard library 
> docstrings.

OK.

I guess docutils isn't in the stdlib (should it be?) or else we could modify
'help' to use it to prepare a straight text formatting.

cheers,
--titus
-- 
C. Titus Brown, c...@msu.edu
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Michael Foord]

On 07/07/2010 17:06, Shashwat Anand wrote:



On Wed, Jul 7, 2010 at 9:24 PM, C. Titus Brown > wrote:


Hi all,

over on the fellowship o' the packaging mailing list, one of our
GSoC students
(merwok) asked about how much formatting info should go into
Python stdlib
docstrings.  Right now the stdlib docstrings are primarily text,
AFAIK; but
with the switch to Sphinx for the official Python docs, should we
permit
ReST-general and/or Sphinx-specific markup in docstrings?

Hmm, I don't actually see that the stdlib docstrings are imported
into the
Python documentation anywhere, so maybe the use of Sphinx isn't that
relevant.  But how about ReST in general?


So will we be able to use .__docs__ within python interpretor, which 
is quite handy feature.

>>> print(os.getcwd.__doc__)
getcwd() -> path

Return a string representing the current working directory.
Also some python interpretors like bpython uses it ; a snapshot here - 
 http://cl.ly/c5bb3be4a01d9d44732f

So will it be ok to break them ?


Using ReST won't *break* these tools, but may make the output less 
readable.


I would say that the major use of docstrings is for interactive help - 
so interactive readability should be *the most important* (but perhaps 
not only) factor when considering how to format standard library docstrings.


Michael



See

http://sphinx.pocoo.org/markup/index.html

for sphinx-specific markup constructs.

thanks,
--titus
--
C. Titus Brown, c...@msu.edu 



___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.uk
   



--
http://www.ironpythoninaction.com/
http://www.voidspace.org.uk/blog

READ CAREFULLY. By accepting and reading this email you agree, on behalf of your 
employer, to release me from all obligations and waivers arising from any and all 
NON-NEGOTIATED agreements, licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap, 
confidentiality, non-disclosure, non-compete and acceptable use policies ("BOGUS 
AGREEMENTS") that I have entered into with your employer, its partners, licensors, 
agents and assigns, in perpetuity, without prejudice to my ongoing rights and privileges. 
You further represent that you have the authority to release me from any BOGUS AGREEMENTS 
on behalf of your employer.


___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[C. Titus Brown]

On Wed, Jul 07, 2010 at 09:36:10PM +0530, Shashwat Anand wrote:
> On Wed, Jul 7, 2010 at 9:24 PM, C. Titus Brown  wrote:
> 
> > Hi all,
> >
> > over on the fellowship o' the packaging mailing list, one of our GSoC
> > students
> > (merwok) asked about how much formatting info should go into Python stdlib
> > docstrings.  Right now the stdlib docstrings are primarily text, AFAIK; but
> > with the switch to Sphinx for the official Python docs, should we permit
> > ReST-general and/or Sphinx-specific markup in docstrings?
> >
> > Hmm, I don't actually see that the stdlib docstrings are imported into the
> > Python documentation anywhere, so maybe the use of Sphinx isn't that
> > relevant.  But how about ReST in general?
> 
> So will we be able to use .__docs__ within python interpretor, which is
> quite handy feature.
> >>> print(os.getcwd.__doc__)
> getcwd() -> path
> 
> Return a string representing the current working directory.
> Also some python interpretors like bpython uses it ; a snapshot here -  h
> ttp://cl.ly/c5bb3be4a01d9d44732f
> So will it be ok to break them ?

I don't understand...

Frist, you can already use

help(os.getcwd)

to get the same result.

Second, what would we be breaking?  We'd be making the straight text
representation a bit more cluttered in return for adding certain kinds
of meta-information into the markup.  I think it's a judgement call...

cheers,
--titus
-- 
C. Titus Brown, c...@msu.edu
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Re: [Python-Dev] query: docstring formatting in python distutils code

[Shashwat Anand]

On Wed, Jul 7, 2010 at 9:24 PM, C. Titus Brown  wrote:

> Hi all,
>
> over on the fellowship o' the packaging mailing list, one of our GSoC
> students
> (merwok) asked about how much formatting info should go into Python stdlib
> docstrings.  Right now the stdlib docstrings are primarily text, AFAIK; but
> with the switch to Sphinx for the official Python docs, should we permit
> ReST-general and/or Sphinx-specific markup in docstrings?
>
> Hmm, I don't actually see that the stdlib docstrings are imported into the
> Python documentation anywhere, so maybe the use of Sphinx isn't that
> relevant.  But how about ReST in general?
>

So will we be able to use .__docs__ within python interpretor, which is
quite handy feature.
>>> print(os.getcwd.__doc__)
getcwd() -> path

Return a string representing the current working directory.
Also some python interpretors like bpython uses it ; a snapshot here -  h
ttp://cl.ly/c5bb3be4a01d9d44732f
So will it be ok to break them ?


>
> See
>
>http://sphinx.pocoo.org/markup/index.html
>
> for sphinx-specific markup constructs.
>
> thanks,
> --titus
> --
> C. Titus Brown, c...@msu.edu
>
>
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

[Python-Dev] query: docstring formatting in python distutils code

[C. Titus Brown]

Hi all,

over on the fellowship o' the packaging mailing list, one of our GSoC students
(merwok) asked about how much formatting info should go into Python stdlib
docstrings.  Right now the stdlib docstrings are primarily text, AFAIK; but
with the switch to Sphinx for the official Python docs, should we permit
ReST-general and/or Sphinx-specific markup in docstrings?

Hmm, I don't actually see that the stdlib docstrings are imported into the
Python documentation anywhere, so maybe the use of Sphinx isn't that
relevant.  But how about ReST in general?

See

http://sphinx.pocoo.org/markup/index.html

for sphinx-specific markup constructs.

thanks,
--titus
-- 
C. Titus Brown, c...@msu.edu
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com