SublimeAutoDocstring
====================

SublimeText plugin for inserting / updating docstrings in Python after analyzing
function parameters and the like.

Features
--------

  - Inspects function definitions and inserts a stub for each parameter
  - Inspects class / module attributes and inserts a stub for each
  - Convert single docstrings or whole modules from one style to another with one command
  - Pull parameter and return type information from Python 3 annotations
  - Discovers what exceptions are raised in a function and inserts a stub for each
  - Rearranges parameters to reflect their order in the function definition
  - Automatically detects style: [Google](https://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html "Example of Google Style")  or [Numpy](https://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_numpy.html "Example of Numpy Style")

Installation
------------

This plugin is indexed on [Package Control](https://packagecontrol.io "Package Control"). Once Package Control is installed, this package can be installed from the command palette using ``Package Control: Install Package``.

Alternatively, you can unzip this repository into your ``Packages`` directory. This directory is easily opened using the ``Sublime Text > Preferences > Browse Packages...`` menu on MacOS, or ``Preferences > Browse Packages...`` on Linux / Windows.

Usage
-----

  Use these keyboard shortcuts, or the commands below from the Command Pallete.

  - <`cmd` + `alt` + `'`> will update a docstring for the first module/class/function preceding the cursor.
  - <`cmd` + `alt` + `shift` + `'`> will update docstrings for every class/method/function in the current file

  Note that on linux / windows, `ctrl` is used in place of `cmd`.

Commands
--------

  - `AutoDocstring: Current`: Create or update the docstring for the next declaration that preceeds the cursor
  - `AutoDocstring: All`: Create or update docstrings for all declarations in a module
  - `AutoDocstring: Convert...`: Convert the docstring of the the next declaration that preceeds the cursor to a specific style
  - `AutoDocstring: Convert All...`: Convert all existing docstrings in a module to a specific style

Settings
--------

  A shortcut to open the settings file is in menu under `Preferences/Package Settings/AutoDocstring/Settings - User`. Settings can also be in a JSON hash (dictionary) called "AutoDocstring" in a project-settings file. Project settings will override package settings.

  - `default_description` *(default="Description")*: Filler text for descriptions
  - `default_return_name` *(default="name")*: Numpy style only. Default parameter name for return values. Set as an empty string to leave return values unnamed.
  - `default_summary` *(default="Summary")*: Filler text for summary
  - `default_type` *(default="TYPE")*: Filler text for type
  - `default_qstyle` *(default=""")*: Type of quote to use for new docstrings.
  - `inspect_class_attributes` *(default=true)*: add / remove class attributes to stay in sync with the code
  - `inspect_exceptions` *(default=true)*: add / remove exceptions to stay in sync with the code.
  - `inspect_function_parameters` *(default=true)*: add / remove function parameters to stay in sync with the code.
  - `inspect_module_attributes` *(default=true)*: add / remove module attributes to stay in sync with the code.
  - `optional_tag` *(default="optional")*: text to add to the type of keyword arguments. Supplying an empty string won't add anything special to new keyword arguments.
  - `sort_class_attributes` *(default=true)*: Whether or not to alphabetically sort class attributes.
  - `sort_exceptions` *(default=true)*: Whether or not to alphabetically sort exceptions.
  - `sort_module_attributes` *(default=true)*: Whether or not to alphabetically sort module attributes.
  - `style` *(default="auto_google")*: can be "google", "numpy", or "auto" for auto-detection based on the other docstrings in the module. A fallback can be specified with something like "auto_google" in case auto-detection fails.
  - `template_order` *(default=false)*: If true, then reorder sections to the same order that they appear in the style's template. If false, section order of existings docstrings is preserved.
  - `use_snippet` *(default=true)*: If true, then insert a snippet so that you can
  tab through newly inserted fields (Summary / Types / Desciptions).
  - `start_with_newline` *(default="")*: Comma separated list of styles ('numpy', 'google') for which you want new docstrings to start with a newline. Can also be true or false to affect all styles.
  - `extra_class_newlines` *default=true*: According to PEP257, docstrings for classes should be surrounded by extra blank lines. Set this to false for more compact, but less PEP257 compliant class docstrings.
  - `keep_previous` *(default=false)*: If true, then always append the existing docstring to the newly updated docstring. Could be useful for *processing legacy code*.