epydoc reST markup for stdlib docstrings

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
46 messages Options
123
Reply | Threaded
Open this post in threaded view
|

epydoc reST markup for stdlib docstrings

Barry Warsaw
Hello Doc-Siggers,

During some recent work on the PEP 3147, I had a need to add some
documentation (docstrings) to some new functions.  To document the function
arguments I added epydoc reST style markup:

def ensure_bytecode_path(bytecode_path):
    """Ensure that the __pycache__ directory for PEP 3147 pyc file exists.

    :param bytecode_path: File system path to PEP 3147 pyc file.
    """

Now, I didn't even think twice about this because several of the larger Python
projects I work on have already adopted epydoc reST markup for API.  During
his review, Antoine disapproved of this, pointing to PEPs 257 and 287.  My
reading of these PEPs however, certainly doesn't prohibit the use of epydoc
reST markup.  Georg and I pointed to the lack of a clear, consistent convention
in the Python stdlib.  I would like to propose that epydoc reST markup be made
that convention.

http://epydoc.sourceforge.net/epydoc.html#epydoc-fields

PEP 257 does include an example for keyword arguments, but not much more is
said about them.  epydoc reST markup is compliant with PEP 287 IMO, by
adopting reST syntax.  I think Sphinx does a pretty good job of handling such
API markup too.

A PEP might be necessary to make this a firm decision.  What do you think
about adopting epydoc reST markup for documenting the stdlib API?

-Barry

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig

signature.asc (853 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: epydoc reST markup for stdlib docstrings

jalopyuser
Good with me, but...

Is epydoc still being maintained?  The last release was over two years
ago, and the current release (3.0) doesn't work with the current
docutils (0.6).

https://sourceforge.net/tracker/?func=detail&aid=2895197&group_id=32455&atid=405618

Bill
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: epydoc reST markup for stdlib docstrings

Michael Foord-5
On 13/04/2010 23:56, Bill Janssen wrote:
> Good with me, but...
>
> Is epydoc still being maintained?  The last release was over two years
> ago, and the current release (3.0) doesn't work with the current
> docutils (0.6).
>    

I don't think that is particularly relevant to the proposal. The
proposal is that we adopt a standard, once we have done that other tools
can be built that use it. Epydoc maybe essentially dead but it doesn't
affect the quality (or otherwise) of the docstring standard.

Michael

> https://sourceforge.net/tracker/?func=detail&aid=2895197&group_id=32455&atid=405618
>
> Bill
> _______________________________________________
> Doc-SIG maillist  -  [hidden email]
> http://mail.python.org/mailman/listinfo/doc-sig
>    


--
http://www.ironpythoninaction.com/

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: epydoc reST markup for stdlib docstrings

Georg Brandl-2
In reply to this post by Barry Warsaw
Am 13.04.2010 21:12, schrieb Barry Warsaw:

> Hello Doc-Siggers,
>
> During some recent work on the PEP 3147, I had a need to add some
> documentation (docstrings) to some new functions.  To document the function
> arguments I added epydoc reST style markup:
>
> def ensure_bytecode_path(bytecode_path):
>     """Ensure that the __pycache__ directory for PEP 3147 pyc file exists.
>
>     :param bytecode_path: File system path to PEP 3147 pyc file.
>     """
>
> Now, I didn't even think twice about this because several of the larger Python
> projects I work on have already adopted epydoc reST markup for API.  During
> his review, Antoine disapproved of this, pointing to PEPs 257 and 287.  My
> reading of these PEPs however, certainly doesn't prohibit the use of epydoc
> reST markup.  Georg and I pointed to the lack of a clear, consistent convention
> in the Python stdlib.  I would like to propose that epydoc reST markup be made
> that convention.
>
> http://epydoc.sourceforge.net/epydoc.html#epydoc-fields

So far, so good, but I would *not* want to make a ":param foo:" section
a recommendation or even mandatory.  (IMO it's too verbose, parameters can be
explained in the text just fine.)  Valid reST is a first goal, and it should
be achievable to slowly convert docstrings to that.

> PEP 257 does include an example for keyword arguments, but not much more is
> said about them.  epydoc reST markup is compliant with PEP 287 IMO, by
> adopting reST syntax.  I think Sphinx does a pretty good job of handling such
> API markup too.

Yes, I've tried to be compatible to what Epydoc supports.

> A PEP might be necessary to make this a firm decision.  What do you think
> about adopting epydoc reST markup for documenting the stdlib API?

>From me, +1.

(Also for this reason: Many projects pull docstrings into their Sphinx docs
via autodoc these days, and some also document inherited APIs.  When these
inherited APIs come from the stdlib, the markup is often confusing or not
even valid reST.)

Georg

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: epydoc reST markup for stdlib docstrings

Michael Foord-5
On 14/04/2010 01:25, Georg Brandl wrote:

> [snip...]
>> A PEP might be necessary to make this a firm decision.  What do you think
>> about adopting epydoc reST markup for documenting the stdlib API?
>>      
> > From me, +1.
>
> (Also for this reason: Many projects pull docstrings into their Sphinx docs
> via autodoc these days, and some also document inherited APIs.  When these
> inherited APIs come from the stdlib, the markup is often confusing or not
> even valid reST.)
>    

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.

Michael Foord

> Georg
>
> _______________________________________________
> Doc-SIG maillist  -  [hidden email]
> http://mail.python.org/mailman/listinfo/doc-sig
>    


--
http://www.ironpythoninaction.com/

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: epydoc reST markup for stdlib docstrings

Ralf Gommers-2


On Wed, Apr 14, 2010 at 7:30 AM, Michael Foord <[hidden email]> wrote:
On 14/04/2010 01:25, Georg Brandl wrote:
[snip...]

A PEP might be necessary to make this a firm decision.  What do you think
about adopting epydoc reST markup for documenting the stdlib API?
   
> From me, +1.

(Also for this reason: Many projects pull docstrings into their Sphinx docs
via autodoc these days, and some also document inherited APIs.  When these
inherited APIs come from the stdlib, the markup is often confusing or not
even valid reST.)
 

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.

Agreed that a reST based standard would be very useful.

One point that is important to me (and many scientific users) is how the docstring looks in a terminal. Numpy has been developing a standard for docstrings and writing docs that both looks good in plain text and in docs rendered with Sphinx. http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines This is quickly becoming a standard for scientific projects (numpy, scipy, matplotlib, ipython etc). For an example see http://docs.scipy.org/numpy/docs/numpy.core.multiarray.arange/, click "source" for plain text version. Basic format is:

"""Summary line.

Parameters
------------
param1 : int
    Description of param1. Can be multi-line.
param2: array
   Description of param2.

Returns
-------
val1 : float

Example
-------
<examples in doctest format>
"""

There is also a very nice wiki doc editor with svn merging support (into the wiki automatic, patch generation for import into svn) here: http://docs.scipy.org/numpy/docs/.

As far as I can tell the epydoc standard is not nearly as readable as the numpy standard in plain text, so please consider the latter or something similar for adoption.

Best regards,
Ralf
 


_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: epydoc reST markup for stdlib docstrings

Barry Warsaw
In reply to this post by Georg Brandl-2
On Apr 13, 2010, at 11:25 PM, Georg Brandl wrote:

>So far, so good, but I would *not* want to make a ":param foo:" section
>a recommendation or even mandatory.  (IMO it's too verbose, parameters can be
>explained in the text just fine.)  Valid reST is a first goal, and it should
>be achievable to slowly convert docstrings to that.

I actually find prose descriptions of parameters and return values much harder
to read.  YMMV of course.

We can definitely agree on valid reST being the top priority, as PEP 287
states.  Even this of course is not mandatory (yet).

I think it is useful to be more prescriptive, such that if folks want to
markup their parameters in other than prose, epydoc reST style is the
officially preferred format to use.  That way, we can begin to standardize the
stdlib, and build and extend tools that read that format.

>> PEP 257 does include an example for keyword arguments, but not much more is
>> said about them.  epydoc reST markup is compliant with PEP 287 IMO, by
>> adopting reST syntax.  I think Sphinx does a pretty good job of handling such
>> API markup too.
>
>Yes, I've tried to be compatible to what Epydoc supports.

Excellent.

>> A PEP might be necessary to make this a firm decision.  What do you think
>> about adopting epydoc reST markup for documenting the stdlib API?
>
>>From me, +1.
>
>(Also for this reason: Many projects pull docstrings into their Sphinx docs
>via autodoc these days, and some also document inherited APIs.  When these
>inherited APIs come from the stdlib, the markup is often confusing or not
>even valid reST.)

Yep.  I'd love to see guidelines and stronger recommendations that people can
follow so that over time, we fix this.

Thanks,
-Barry

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig

signature.asc (853 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: epydoc reST markup for stdlib docstrings

Barry Warsaw
In reply to this post by Michael Foord-5
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 the rules are very simple, and once
learned are easy to remember.

-Barry

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig

signature.asc (853 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: epydoc reST markup for stdlib docstrings

David Goodger
In reply to this post by Barry Warsaw
On Tue, Apr 13, 2010 at 17:12, Barry Warsaw <[hidden email]> wrote:

> During some recent work on the PEP 3147, I had a need to add some
> documentation (docstrings) to some new functions.  To document the function
> arguments I added epydoc reST style markup:
>
> def ensure_bytecode_path(bytecode_path):
>    """Ensure that the __pycache__ directory for PEP 3147 pyc file exists.
>
>    :param bytecode_path: File system path to PEP 3147 pyc file.
>    """
>
> Now, I didn't even think twice about this because several of the larger Python
> projects I work on have already adopted epydoc reST markup for API.  During
> his review, Antoine disapproved of this, pointing to PEPs 257 and 287.  My
> reading of these PEPs however, certainly doesn't prohibit the use of epydoc
> reST markup.

PEP 257 doesn't address docstring syntax at all, just conventions. PEP
287 addresses "only the low-level syntax of docstrings". IOW, these
PEPs don't apply to Antoine's concern. High-level semantics simply
aren't addressed by them. (As the author or co-author, I should know
:-)

I once wrote up some notes about docstring semantics:
http://docutils.sourceforge.net/docs/dev/semantics.html

> Georg and I pointed to the lack of a clear, consistent convention
> in the Python stdlib.  I would like to propose that epydoc reST markup be made
> that convention.
>
> http://epydoc.sourceforge.net/epydoc.html#epydoc-fields

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* standard convention, allowing for others.

Just as choice of markup is very much a matter of personal preference
(some people *love* dealing with XML directly), choice of API
documentation semantics is also a personal preference thing. We would
be wise to allow for choice.

--
David Goodger <http://python.net/~goodger>
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: epydoc reST markup for stdlib docstrings

Barry Warsaw
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* standard convention, allowing for others.
>
>Just as choice of markup is very much a matter of personal preference
>(some people *love* dealing with XML directly), choice of API
>documentation semantics is also a personal preference thing. We would
>be wise to allow for choice.

Perhaps it would be useful to survey some popular and/or large Python code
bases to see what is currently being used?  That would be a good start to try
to figure out what the stdlib should recommend.

I do think that we should make strong recommendations for the standard
library, so that we have consistency and good online documentation.  I
personally like epydoc reST format (not JavaDoc) but I'm sure there are other
decent formats.

-Barry

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig

signature.asc (853 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: epydoc reST markup for stdlib docstrings

Michael Foord-5
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 making the
epydoc field conventions *a* standard convention, allowing for others.

Just as choice of markup is very much a matter of personal preference
(some people *love* dealing with XML directly), choice of API
documentation semantics is also a personal preference thing. We would
be wise to allow for choice.
    
Perhaps it would be useful to survey some popular and/or large Python code
bases to see what is currently being used?  That would be a good start to try
to figure out what the stdlib should recommend.

I do think that we should make strong recommendations for the standard
library, so that we have consistency and good online documentation.  I
personally like epydoc reST format (not JavaDoc) but I'm sure there are other
decent formats.
  

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?

I don't recall *ever* seeing a consistent pattern for specifying parameters and return values in Python docstrings.

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...

Michael

-Barry
  
_______________________________________________ Doc-SIG maillist - [hidden email] http://mail.python.org/mailman/listinfo/doc-sig


-- 
http://www.ironpythoninaction.com/

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: epydoc reST markup for stdlib docstrings

Barry Warsaw
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 (IMNSHO :).

As far as epydoc, this is probably the only page you care about:

http://epydoc.sourceforge.net/manual-fields.html

It describes the fields that are used to describe parameters, return types,
and exceptions.

Note that while the body of that page uses "Epytext" format, the table near
the top of the page shows the three alternative syntaxes.  Of those of course
I recommend reST (the middle column).  You have to mentally translate the
syntax in the body of the page to reST though.

Keep in mind too that it's not always necessary to include *every* field in a
function's docstring.  Obviously, include only what is useful to the consumer
of the function's documentation.  For example, when it's completely obvious,
or when I actually don't know (e.g. because the method proxies some other
method 3 levels deep), I might not include the :type: field.  I also won't
include obvious, common exceptions.  I do think *that* can be left to the
author's taste.

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 inject.
    :type msg: `email.message.Message` or derived
    :param recips: Optional set of recipients to put into the message's
        metadata.
    :type recips: sequence of strings
    :param switchboard: Optional name of switchboard to inject this message
        into.  If not given, the 'in' switchboard is used.
    :type switchboard: string
    :param kws: Additional values for the message metadata.
    :type kws: dictionary
    """

Note that :param: values are complete sentences, while :type: values are
informative types, not necessarily explicit types (e.g. an interface for mlist
and 'string' instead of 'str' or 'unicode' for switchboard).  This function
doesn't return anything and doesn't explicitly raise any exceptions.  The
implicit KeyErrors that could be raised are not described.

>I don't recall *ever* seeing a consistent pattern for specifying
>parameters and return values in Python docstrings.

Exactly. :)

>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...

Like all other coding standards we have for the stdlib, the migration can
happen opportunistically over time.  But folks need a target or nothing will
ever happen.

-Barry

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig

signature.asc (853 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: epydoc reST markup for stdlib docstrings

Fred Drake-3
In reply to this post by Michael Foord-5
On Wed, Apr 14, 2010 at 8:44 AM, Michael Foord
<[hidden email]> 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 ReST, didn't we?  :-)

If we can come up with a good recommendation, it'll take hold fairly
thoroughly.  Not quickly at first, but once there's value (tools) to
be had it'll happen.

The value for the standard library is that the documentation
maintenance can be moved closer to the code, and is less likely to get
out of sync.


  -Fred

--
Fred L. Drake, Jr.    <fdrake at gmail.com>
"Chaos is the score upon which reality is written." --Henry Miller
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: epydoc reST markup for stdlib docstrings

Nick Coghlan
In reply to this post by Barry Warsaw
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 the rules are very simple, and once
> learned are easy to remember.

Did you look at the NumPy guidelines Ralf posted?:
http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines

Those look very clean to me, and fairly similar to what we already do in
the ReST docs.

Because epydoc works with tags rather than sections, it looks a lot
"noisier" to me when reading the plain text version.

Cheers,
Nick.

--
Nick Coghlan   |   [hidden email]   |   Brisbane, Australia
---------------------------------------------------------------
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: epydoc reST markup for stdlib docstrings

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 for parameters (etc) well enough
>>> to have an opinion on that.
>>
>> The thing I like about them is that the rules are very simple, and once
>> learned are easy to remember.
>
>Did you look at the NumPy guidelines Ralf posted?:
>http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
>
>Those look very clean to me, and fairly similar to what we already do in
>the ReST docs.
>
>Because epydoc works with tags rather than sections, it looks a lot
>"noisier" to me when reading the plain text version.
And I'm not keen on the sections since I think they consume too much vertical
whitespace.  And I like the tags of epydoc format on the left side for their
regularity.  Everyone's got a different opinion, and the only one that matters
is the BDFL's. :)

OTOH, the specifics don't matter as much as just picking one for the stdlib.

-Barry


_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig

signature.asc (853 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: epydoc reST markup for stdlib docstrings

Georg Brandl-2
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 for parameters (etc) well enough
>>>> to have an opinion on that.
>>>
>>> The thing I like about them is that the rules are very simple, and once
>>> learned are easy to remember.
>>
>>Did you look at the NumPy guidelines Ralf posted?:
>>http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
>>
>>Those look very clean to me, and fairly similar to what we already do in
>>the ReST docs.
>>
>>Because epydoc works with tags rather than sections, it looks a lot
>>"noisier" to me when reading the plain text version.
>
> And I'm not keen on the sections since I think they consume too much vertical
> whitespace.  And I like the tags of epydoc format on the left side for their
> regularity.

Also, the numpy docstring conventions also aren't valid reST and therefore
need preprocessing.  (Making them reST isn't hard but requires even more
vertical space.)

Georg

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: epydoc reST markup for stdlib docstrings

Georg Brandl-2
In reply to this post by Fred Drake-3
Am 14.04.2010 13:08, schrieb Fred Drake:
> On Wed, Apr 14, 2010 at 8:44 AM, Michael Foord
> <[hidden email]> 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 ReST, didn't we?  :-)

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.

> If we can come up with a good recommendation, it'll take hold fairly
> thoroughly.  Not quickly at first, but once there's value (tools) to
> be had it'll happen.
>
> The value for the standard library is that the documentation
> maintenance can be moved closer to the code, and is less likely to get
> out of sync.

Exactly.

Georg

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: epydoc reST markup for stdlib docstrings

Nick Coghlan
In reply to this post by Barry Warsaw
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 inject.
>     :type msg: `email.message.Message` or derived
>     :param recips: Optional set of recipients to put into the message's
>         metadata.
>     :type recips: sequence of strings
>     :param switchboard: Optional name of switchboard to inject this message
>         into.  If not given, the 'in' switchboard is used.
>     :type switchboard: string
>     :param kws: Additional values for the message metadata.
>     :type kws: dictionary
>     """

Since the NumPy conventions seem to be the only real alternative
proposed so far, here's what the above would look like (according to my
ever so comprehensive 5 minute skim of those guidelines, anyway...)

def inject_message(mlist, msg, recips=None, switchboard=None, **kws):
    """Inject a message into a queue.

    Parameters
    ----------
    mlist : IMailingList
        The mailing list this message is destined for.
    msg : email.message.Message (or derived)
        The message object to inject.
    recips : sequence of strings, optional
        Optional set of recipients to put into the message's
        metadata.
    switchboard : string, optional
        Optional name of switchboard to inject this message
        into.  If not given, the 'in' switchboard is used.
    kws : dictionary, optional
        Additional values for the message metadata.
    """

Basically, the numpy format trades a couple of lines of whitespace for
the section header to get rid of the tag noise in the individual
parameter descriptions.

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 are required, not those which are optional.

Cheers,
Nick.

--
Nick Coghlan   |   [hidden email]   |   Brisbane, Australia
---------------------------------------------------------------
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: epydoc reST markup for stdlib docstrings

Fred Drake-3
On Wed, Apr 14, 2010 at 10:27 AM, Nick Coghlan <[hidden email]> 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 are required, not those which are optional.

This has always been a source of tension in documenting Python: a
certain amount of information is available in the signature, but the
signature of the implementation function isn't always the same as the
signature of the contract.  Documentation needs the later.

Interfaces help, if you use them (ABCs kinda, if you follow that
school of thought).  Unfortunately, there's not really a way currently
to tell the difference between "default implementation" and "contract"
in ABCs, which is all stock Python provides.


  -Fred

--
Fred L. Drake, Jr.    <fdrake at gmail.com>
"Chaos is the score upon which reality is written." --Henry Mille
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: epydoc reST markup for stdlib docstrings

Fred Drake-3
In reply to this post by Georg Brandl-2
On Wed, Apr 14, 2010 at 10:26 AM, Georg Brandl <[hidden email]> 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 that we should sucker you into another such
task, but just noting that someone's likely to find the outcome
sufficiently valuable.  And yes, multiple hands would be better.


  -Fred

--
Fred L. Drake, Jr.    <fdrake at gmail.com>
"Chaos is the score upon which reality is written." --Henry Miller
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
123