dextreem / SublimeAutoDocstring

Insert or update python docstrings; an improved docblockr for python

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 or Numpy

Installation

This plugin is indexed on 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.