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 annotation default	Method, def's argument ---------------------------+ Argument's type hint ---------------------------+ 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.