doq

Docstring generator.

Installation

$ pip install doq

How to use

$ cat spam.py
def spam(arg1, arg2: str) -> str:
    pass

$ cat spam.py | doq
def spam(arg1, arg2: str) -> str:
  """spam.

  :param arg1:
  :param arg2:
  :type arg2: str
  :rtype: str
  """
  pass

Default formatter is sphinx. You can choose sphinx, google or numpy.

$ cat spam.py | doq --formatter=google
def spam(arg1, arg2: str) -> str:
  """spam.

  Args:
      arg1 : arg1
      arg2 (str): arg2

  Returns:
      str:
  """
  pass

$ cat spam.py | doq --formatter=numpy
def spam(arg1, arg2: str) -> str:
  """spam.

  Parameters
  ----------
  arg1
        arg1
  arg2 : str
       arg2

  Returns
  -------
  str

  """
  pass

Usage

$ python -m doq.cli --help
usage: doq [-h] [-f FILE] [--start START] [--end END] [-t TEMPLATE_PATH]
           [-s STYLE] [--formatter FORMATTER] [--indent INDENT] [--omit OMIT]
           [-r] [-d DIRECTORY] [-w] [-v] [-c CONFIG] [--ignore_exception]
           [--ignore_yield] [--ignore_init]

Docstring generator.

optional arguments:
  -h, --help            show this help message and exit
  -f FILE, --file FILE  File or STDIN
  --start START         Start lineno
  --end END             End lineno
  -t TEMPLATE_PATH, --template_path TEMPLATE_PATH
                        Path to template directory
  -s STYLE, --style STYLE
                        Output style string or json
  --formatter FORMATTER
                        Docstring formatter. sphinx,google or numpy
  --indent INDENT       Indent number
  --omit OMIT           Omit first argument such as self
  -r, --recursive       Run recursively over directories
  -d DIRECTORY, --directory DIRECTORY
                        Path to directory
  -w, --write           Edit files in-place
  -v, --version         Output the version number
  -c CONFIG, --config CONFIG
                        Path to a setup.cfg or pyproject.toml
  --ignore_exception    Ignore exception statements
  --ignore_yield        Ignore yield statements
  --ignore_init         Ignore generate docstring to __init__ method

Customize template

doq use Jinja2 template. So you can create your own template.

Note

You must create 3 template files.

File name	Description
class.txt	class docstring
def.txt	def / method docstring
noarg.txt	def / method without argument docstring

Available Jinja2's variable

Name		Description
name		class, method, def's name
params	argument	Method, def's argument
	annotation	Argument's type hint
	default	Defaut keyword argument
exceptions		List of exception
yields		List of yield
return_type		Return type hint

See examples

Configuration

doq will automatically search setup.cfg or pyproject.toml in your project.

Note

ignore_exception, ignore_exception and ignore_init can set true only. If you want turn off, remove from configuration.

setup.cfg

The section must be [doq].

configuration file example:

[doq]
style = "json"
template_path = "/path/to/template"

pyproject.toml

The section must be [tool.doq].

configuration file example:

[tool.doq]
style = "json"
template_path = "/path/to/template"

Completion

This program provides shell completions. It should be out of box if you install it from a wheel file.

LICENSE

NEW BSD LICENSE.