numpydoc.el

An Emacs Lisp package to automatically insert NumPy style
docstrings in
Python function definitions.

Calling numpydoc-generate parses the function at point (the cursor
can be anywhere in the function body). The parsing detects argument
names, type hints, exceptions, and the return type hint. This
information is used to generate a docstring.

The default behavior is to prompt the user (in the minibuffer) for a
short & long description of the function, a description for each
function argument, a description for each possible exception, and a
description for the return. It’s also possible to either disable the
minibuffer prompt or use
yasnippet insertion. See
customization for more information. You’ll also find
a few examples below. See the
NEWS
file to see recent changes.

Setup

Pick your favorite method of Emacs Lisp package setup:

;; use-package with :ensure t to intall from MELPA.
(use-package numpydoc
  :ensure t)
;; use the straight.el package manager.
(straight-use-package 'numpydoc)
;; clone the git respository and require
(add-to-list 'load-path "/path/to/numpydoc.el")
(require 'numpydoc)
;; or point use-package to the local clone
(use-package numpydoc
  :load-path "/path/to/numpydoc.el")

The C-c C-n binding is vacant (not used in python.el, as of
writing this), so you may want to give yourself a convenient shortcut:

;; with use-package
(use-package numpydoc
  :ensure t
  :bind (:map python-mode-map
              ("C-c C-n" . numpydoc-generate)))
;; without
(add-to-list 'load-path "/path/to/numpydoc.el")
(require 'numpydoc)
(define-key python-mode-map (kbd "C-c C-n") #'numpydoc-generate)

Customization

View customizations without leaving Emacs via M-x customize-group
RET numpydoc

numpydoc-insertion-style

The method used to insert components of the docstring (default is
‘prompt).

• ‘prompt will trigger a request for each description
  in the minibuffer.


• ‘yas (requires yasnippet to be
  installed) will generate a template and call
  yas-expand-snippet, providing an insertion method
  familiar to yasnippet users.


• nil will disable any interactive insertion (template
  text will be inserted).

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 (the default) an Examples block will be added to
the docstring.

numpydoc-insert-parameter-types

If t (the default) type hints from the function
signature will be used to add a type to each argument in the
Parameters block of the docstring.

numpydoc-insert-raises-block

If t (the default) a Raises bock will be added to the
docstring if exceptions are detected in the function body.

numpydoc-insert-return-without-typehint

If t a Returns block will be inserted in the absence of
a return type hint.

numpydoc-template-short

Template text that will be used as the short description if
numpydoc-insertion-style is nil.

numpydoc-template-long

Template text that will be used as the long description if
numpydoc-insertion-style is nil.

numpydoc-template-arg-desc

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

numpydoc-template-type-desc

Template text that will be used for each function argument type
description if numpydoc-insertion-style is
nil.

numpydoc-ignored-params

All function parameters with names listed here will be ignored
when generating a docstring.

numpydoc-auto-fill-paragraphs

If t text that is inserted in a prompt will be
automatically paragraph-filled.

Examples

M-x numpydoc-generate with the default configuration,
numpydoc-insertion-style set to 'prompt (notice how long text is
automatically paragraph-filled):

Using yasnippet (numpydoc-insertion-style set to 'yas):

With numpydoc-insertion-style set to nil; before:

def plot_histogram(
    x: np.ndarray,
    bins: int = 10,
    range: tuple[float, float] | None = None,
    weights: np.ndarray | None = None,
    flow: bool = False,
    ax: plt.Axes | None = None,
) -> tuple[plt.Figure, plt.Axes]:
    if weights is not None:
        if weights.shape != np.shape:
            raise ValueError("x and weights must have same shape.")
    pass

After M-x numpydoc-generate:

def plot_histogram(
    x: np.ndarray,
    bins: int = 10,
    range: tuple[float, float] | None = None,
    weights: np.ndarray | None = None,
    flow: bool = False,
    ax: plt.Axes | None = 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 : tuple[float, float], optional
        FIXME: Add docs.
    weights : np.ndarray, optional
        FIXME: Add docs.
    flow : bool
        FIXME: Add docs.
    ax : plt.Axes | None
        FIXME: Add docs.
    Returns
    -------
    tuple[plt.Figure, plt.Axes]
        FIXME: Add docs.
    Raises
    ------
    ValueError
        FIXME: Add docs.
    Examples
    --------
    FIXME: Add docs.
    """
    if weights is not None:
        if weights.shape != np.shape:
            raise ValueError("x and weights must have same shape.")
    pass

Similar packages

• sphinx-doc.el: Inserts
  sphinx-compatible docstrings (does not offer customizations or
  automatically formatted insertions from the minibuffer or yasnippet).
• docstr: Docstring insertion
  support for any programming language, including NumPy style Python
  (it has a programmable interface but requires a bit more setup to
  get the utility provided numpydoc.el).