Consolidated Fields
===================

.. automodule:: fox

`Sphinx`_ can use `consolidated fields`_ with mixed results.

Without
-------

The first example is traditional Sphinx with some extra glitz.

.. autofunction:: foxy

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.

.. autofunction:: fox_velocity

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.

.. autofunction:: fox_speed

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

.. _Sphinx: http://sphinx-docs.org

.. _consolidated fields: \
    http://epydoc.sourceforge.net/manual-othermarkup.html#consolidated-fields