Sphinx can use consolidated fields with mixed results.
The first example is traditional Sphinx with some extra glitz.
Return the maximum speed for a fox.
| Parameters: |
|
|---|---|
| Returns: |
|
It was autodoc’d from this docstrings:
def foxy(size, weight, age):
"""
Return the maximum speed for a fox.
:parameter size: The size of the fox (in meters)
:parameter weight: The weight of the fox (in stones)
:type weight: float
:parameter age: The age of the fox (in years)
:type age: int
:returns: - **velocity** (`float`) -- The velocity of the fox.
:rtype: `float`
"""
return size / age
The second and third examples are consolidated fields. The second uses bullets and the third indentation.
Return the maximum speed for a fox.
| Parameters : |
|---|
| Returns : |
|---|
Personally I like the indented version, it reads well, and also formats well in sphinx, except the arguments are not boldface, although the arg types are italicized.
Return the maximum speed for a fox.
| Parameters : |
|
|---|---|
| Returns : |
|
Which corresponds to these docstrings:
def fox_velocity(size, weight, age):
"""
Return the maximum speed for a fox.
:Parameters:
- `size`: The size of the fox (in meters)
- `weight`: The weight of the fox (in stones)
- `age`: The age of the fox (in years)
:Returns:
- `velocity`: The velocity of the fox.
"""
return size / age
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)
:Returns:
speed : float
The speed of the fox.
"""
return size / age