macurovc / insert-docstring

This plugin allows the automatic insertion of Google style function docstrings in Python.

Python Docstring Inserter

This repository enables the automatic generation of function docstrings in Python according to the Google style guide. Here is an example:

def fetch_data(url: str, keys: List[int]) -> Mapping[int, str]:
    """This is a short description of this function and can span over multiple
    lines.

    This is a long description of the function with more details about it.

    Args:
        url: This is an argument description, which can span over multiple
            lines too.
        keys: This is a description of the second argument.

    Returns:
        This is a description of the returned data and can be detailed too.

    """

The text gets automatically indented and split on multiple lines.

Install

With MELPA

This package is available on MELPA. You can refer to this page to learn how to use the MELPA repository.

With use-package and quelpa

(use-package python-insert-docstring
  :ensure nil
  :quelpa (python-insert-docstring
           :fetcher github
           :repo "macurovc/insert-docstring"))

Manually

Place python-insert-docstring.el in your Emacs load-path. E.g.:

(add-to-list 'load-path (expand-file-name "~/{path/to}/insert-docstring"))
(require 'python-insert-docstring)

Usage

Set in the ~/.emacs file a keybinding such as:

(defun set-python-keybindings ()
  (local-set-key (kbd "C-c i") 'python-insert-docstring-with-google-style-at-point)
  )
(add-hook 'python-mode-hook 'set-python-keybindings)

Now, in a python file, place the cursor on a function, type C-c i and follow the instructions.

Contributing

Any contribution is welcome. The file python-insert-docstring-tests.el contains tests for the functions that don't require user inputs and don't modify a buffer. The tests can be run with the following command:

emacs -batch -l python-insert-docstring.el -l python-insert-docstring-tests.el -f ert-run-tests-batch-and-exit

Each contribution must respect the following requirements:

• pass the validation of package-lint
• byte-compilation without errors
• no errors with M-x checkdoc

insert-docstring's Issues

How to add properly parameter description?

Hello, I find you package useful, but I have to edit them everytime I use it.

usually the format I use and is advised as example here:

https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google

is:

Args:
    var (type):
        description

There is some way to achieve this?

Kind Regards

Carlo D.