Skip to content
master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.

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.

About

Insert or update python docstrings; an improved docblockr for python

Resources

License

Packages

No packages published

Languages