numpydoc.el

An Emacs Lisp package to automatically insert NumPy style docstrings for Python functions.

Calling numpydoc-generate will parse the function signature (for the function corresponding to the current cursor location) and detects argument names, argument type hints, and return type hints. The default behavior is to prompt the user (in the minibuffer) for a (short and long) description of the function, and a description for each argument and the returned value. If the prompt is off (numpydoc-prompt-for-input is nil), then some customizable template text will be inserted into the docstring. If an existing docstring is detected, you'll be asked if you'd like to delete it and start fresh.

Customization

See inside Emacs with M-x customize-group RET numpydoc

numpydoc-prompt-for-input

If t you will be prompted to enter a short description and long description, a description for each function argument, and a description for the return (if a return type hint is provided).

numpydoc-quote-char

Quote character to use (the default is a double quote, ?\", used throughout the numpydoc docstring guide and the black formatting tool).

numpydoc-insert-examples-block

If t an Examples block will be added to the docstring.

numpydoc-template-short

Template text that will be used as the short description if numpydoc-prompt-for-input is nil.

numpydoc-template-long

Template text that will be used as the long description if numpydoc-prompt-for-input is nil.

numpydoc-template-desc

Template text that will be used for each function argument description if numpydoc-prompt-for-input is nil.

Examples

M-x numpydoc-generate with the default configuration that will prompt for input in the minibuffer (notice how long text is automatically paragraph-filled):

Or, M-x numpydoc-generate with numpydoc-prompt-for-input set to nil:

Before:

def plot_histogram(
    x: np.ndarray,
    bins: int = 10,
    range: Optional[Tuple[float, float]] = None,
    weights: Optional[np.ndarray] = None,
    flow: bool = False,
    ax: Optional[plt.Axes] = None,
) -> Tuple[plt.Figure, plt.Axes]:
    pass

After:

def plot_histogram(
    x: np.ndarray,
    bins: int = 10,
    range: Optional[Tuple[float, float]] = None,
    weights: Optional[np.ndarray] = None,
    flow: bool = False,
    ax: Optional[plt.Axes] = None,
) -> Tuple[plt.Figure, plt.Axes]:
    """FIXME: Short description.

    FIXME: Long description.

    Parameters
    ----------
    x : np.ndarray
        FIXME: Add docs.
    bins : int
        FIXME: Add docs.
    range : Optional[Tuple[float, float]]
        FIXME: Add docs.
    weights : Optional[np.ndarray]
        FIXME: Add docs.
    flow : bool
        FIXME: Add docs.
    ax : plt.Axes
        FIXME: Add docs.

    Returns
    -------
    Tuple[plt.Figure, plt.Axes]
        FIXME: Add docs.

    Examples
    --------
    FIXME: Add docs.

    """
    pass

Similar packages

• sphinx-doc.el: Inserts sphinx-compatible docstrings (does not offer customizations or automatically formatted insertions from minibuffer prompt).