Skip to main content

Docstring generator

Project description

https://github.com/heavenshell/py-doq/workflows/build/badge.svg Python 3 Updates

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] [-r]
           [-d DIRECTORY] [-w] [-v]

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
  -r, --recursive       Run recursively over directories
  -d DIRECTORY, --directory DIRECTORY
                        Dire
  -w, --write           Edit files in-place
  -v, --version         Output the version number

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
return_type Return type hint

See examples

LICENSE

NEW BSD LICENSE.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for doq, version 0.4.1
Filename, size File type Python version Upload date Hashes
Filename, size doq-0.4.1.tar.gz (13.0 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page