douglasdavis / numpydoc.el

Insert NumPy style docstrings in Python functions.

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).