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

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

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.

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

Table Of Contents

Previous topic

NumPyDoc vs. Sphinx and Google Format

This Page