Consolidated Fields

Sphinx can use consolidated fields with mixed results.

Without

The first example is traditional Sphinx with some extra glitz.

fox.foxy(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:

• velocity (float) – The velocity of the fox.

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

With

The second and third examples are consolidated fields. The second uses bullets and the third indentation.

fox.fox_velocity(size, weight, age)

Return the maximum speed for a fox.

Parameters:

• size : float

  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:

• velocity : float

  The velocity of the fox.

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.

fox.fox_speed(size, weight, age)

Return the maximum speed for a fox.

Parameters:

• size – float 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 The speed of the fox.

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