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] [-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"

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.

Source Distribution

doq-0.9.1.tar.gz (12.0 kB view hashes)

Uploaded source

Supported by

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