Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/douglasdavis/numpydoc.el

Insert NumPy style docstrings in Python functions.
https://github.com/douglasdavis/numpydoc.el

docstrings documentation-generator documentation-tool emacs emacs-lisp numpydoc python

Last synced: 3 months ago
JSON representation

Insert NumPy style docstrings in Python functions.

Host: GitHub
URL: https://github.com/douglasdavis/numpydoc.el
Owner: douglasdavis
License: gpl-3.0
Created: 2021-02-11T18:21:11.000Z (almost 4 years ago)
Default Branch: main
Last Pushed: 2023-08-11T17:08:25.000Z (over 1 year ago)
Last Synced: 2023-08-11T23:52:45.971Z (over 1 year ago)
Topics: docstrings, documentation-generator, documentation-tool, emacs, emacs-lisp, numpydoc, python
Language: Emacs Lisp
Homepage:
Size: 3.65 MB
Stars: 37
Watchers: 4
Forks: 6
Open Issues: 3
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

        # numpydoc.el

[![MELPA](https://melpa.org/packages/numpydoc-badge.svg)](https://melpa.org/#/numpydoc)

[![CI](https://github.com/douglasdavis/numpydoc.el/actions/workflows/ci.yml/badge.svg)](https://github.com/douglasdavis/numpydoc.el/actions/workflows/ci.yml)

An Emacs Lisp package to automatically insert [NumPy style

docstrings](https://numpydoc.readthedocs.io/en/latest/format.html) 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](https://github.com/joaotavora/yasnippet) insertion. See

[customization](#customization) for more information. You'll also find

a few [examples](#examples) below. See the

[NEWS](https://github.com/douglasdavis/numpydoc.el/blob/main/NEWS.md)

file to see recent changes.

## Setup

Pick your favorite method of Emacs Lisp package setup:

```elisp

;; 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:

```elisp

;; 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:

```python

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:

```python

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](https://github.com/naiquevin/sphinx-doc.el): Inserts

  sphinx-compatible docstrings (does not offer customizations or

  automatically formatted insertions from the minibuffer or yasnippet).

- [docstr](https://github.com/jcs-elpa/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`).