Python Sphinx autosummary rendering of parameters like numpy

Question

Problem

I am using Sphinx and the autosummary extension to document my python 3 project with numpy style docstring.

Current rendering

This is my current rendering. The red box shows the current layout for parameters and returns.

Desired rendering

I would like to change the layout of parameters and returns like numpy, shown in desired rendering example below, so that parameter name and type is in one line, and the description is indented in another line.

How do I achieve that? (Looking into numpy, scipy, and pandas docs, I couldn't find what special thing did they do to change the rendering.)

Numpy stype docstring

The docstring in the code is:

def modified_main(raw_img_path, ground_truth_img_path, ground_truth_count=None, sort=True):
    """
    Computes deviation of thresholded images using different methods
    compared to user input ground truth image.

    Parameters
    ----------
    raw_img_path : str
        Path of raw image.
    ground_truth_img_path : str
        Path of ground truth image.
    ground_truth_count : int, optional
        User input ground truth cell count.
    sort : bool, optional
        Sort the deviation by majority vote.

    Returns
    -------
    optimal_method : str
        Optimal threshold method.
    optimal_threshold : float
        Threshold given by optimal threshold method.

    """
    pass

Sphinx config

I have included extensions needed for autosummary in the conf.py file:

extensions = ['sphinx.ext.autodoc',
              'sphinx.ext.napoleon',
              'sphinx.ext.autosummary']
autosummary_generate = True
html_theme = 'pydata_sphinx_theme'

The use of autosummary is shown here:

.. currentmodule:: modified

.. autosummary::
   :toctree: api/

   modified_main

Answer 1

The most likely issue is that your formatting of reST in your docstring is not similar to that of empty.

def empty(shape, dtype=None, order='C'):
    """Return a new matrix of given shape and type, without initializing entries.

    Parameters
    ----------
    shape : int or tuple of int
        Shape of the empty matrix.
    dtype : data-type, optional
        Desired output data-type.
    order : {'C', 'F'}, optional
        Whether to store multi-dimensional data in row-major
        (C-style) or column-major (Fortran-style) order in
        memory.

    See Also
    --------
    empty_like, zeros

    .. snip

    """

You did not include an example of your docstring, so I cannot be absolutely certain. Please edit your question to include your docstring.

Answer 2

I have found the solution by really digging into the numpydoc documentation. In the extension variable in conf.py, change the element sphinx.ext.napoleon to numpydoc. The changed variable now looks like

extensions = ['sphinx.ext.autodoc',
              'numpydoc',
              'sphinx.ext.autosummary']

The rendering becomes

where the red box gives desired rendering like that of numpy.