On 10/8/2009 1:53, Guenter Milde wrote:
>
> On 2009-10-07, John H Palmieri wrote:
>
>> On Oct 5, 1:47 pm, Oben<obenso...@googlemail.com> wrote:
>
>>> I browsed a bit in Sage's doc and so far only found the style
>>> mentioned by Fernando (INPUT ..). Do I get you right that you plan to
>>> convert these to :param:... markup in the future?
>
>> A few days ago, I opened a trac ticket for Sage to document this
>> markup and also to use it in one portion of the documentation. I
>> think that it would be nice to eventually convert everything to
>> the :param: markup, but it's pretty low on the priority list for Sage
>> developers.
>
> A main advantage of reST is the nice and intelligable look in plain-text
> format. Using too many roles and directives, this feature is lost.
>
> The docstring should be easy to read and understand also if I get it via
> help(somefun) in a console or x-terminal. Lots of :strange:`markup` can be
> distracting there. Choosing the right default role might help.
The discussion here, to my knowledge, is primarily about using reST
field lists in doc strings (which predate Sphinx, actually, and have
been used by tools such as epydoc), rather than the roles that you are
assuming. An example:
def fox_speed(size, weight, age):
"""
Return the maximum speed for a fox.
:param size: The size of the fox (in meters)
:param weight: The weight of the fox (in stones)
:type weight: float
:param age: The age of the fox (in years)
:type age: int
"""
#[...]
Or better yet, using what epydoc calls "consolidated fields" (because
epydoc was built for javadoc syntax, and reST has some nicer markup
constructs built-in to take advantage of):
def fox_speed(size, weight, age):
"""
Return the maximum speed for a fox.
:Parameters:
size
The size of the fox (in meters)
weight : float
The weight of the fox (in stones)
age : int
The age of the fox (in years)
"""
#[...]
I think this last example is very readable in its ASCII form there, and
will produce nicely formatted results in Sphinx (or epydoc for that matter).
--
--Max Battcher--
http://worldmaker.net
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com
To unsubscribe from this group, send email to
sphinx-dev+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/sphinx-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
