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

Table Of Contents

Previous topic

NumPyDoc vs. Sphinx and Google Format

This Page