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] [--omit OMIT]
         [-r] [-d DIRECTORY] [-w] [-v] [--ignore_exception] [--ignore_yield]

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
                        Dire
  -w, --write           Edit files in-place
  -v, --version         Output the version number
  --ignore_exception    Ignore exception statements
  --ignore_yield        Ignore yield statements

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

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.7.0
Filename, size File type Python version Upload date Hashes
Filename, size doq-0.7.0.tar.gz (10.2 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page