ctrl+shift+p filters: :st2 :st3 :win :osx :linux
Browse

Doc​Blockr_Python

by adambullmer ST3

Sublime Text DocBlockr for python. Simplifies writing docstring comments in Python.

Details

Installs

  • Total 21K
  • Win 13K
  • OS X 4K
  • Linux 4K
Dec 16 Dec 15 Dec 14 Dec 13 Dec 12 Dec 11 Dec 10 Dec 9 Dec 8 Dec 7 Dec 6 Dec 5 Dec 4 Dec 3 Dec 2 Dec 1 Nov 30 Nov 29 Nov 28 Nov 27 Nov 26 Nov 25 Nov 24 Nov 23 Nov 22 Nov 21 Nov 20 Nov 19 Nov 18 Nov 17 Nov 16 Nov 15 Nov 14 Nov 13 Nov 12 Nov 11 Nov 10 Nov 9 Nov 8 Nov 7 Nov 6 Nov 5 Nov 4 Nov 3 Nov 2 Nov 1
Windows 10 31 26 15 25 29 16 24 26 23 34 22 31 15 16 27 38 24 29 24 19 15 28 22 34 21 23 17 18 23 24 24 26 23 19 21 28 24 25 22 33 18 27 38 23 21
OS X 4 3 10 5 4 6 8 2 6 8 8 5 3 5 3 5 3 3 8 5 3 5 8 8 4 3 4 1 3 5 9 8 8 9 7 2 8 10 8 4 4 6 6 3 3 5
Linux 3 7 6 6 5 7 5 5 4 9 5 7 8 2 3 7 7 8 8 8 2 9 8 6 4 12 8 8 7 7 13 4 5 6 5 8 7 9 10 15 9 7 8 12 8 9

Readme

Source
raw.​githubusercontent.​com

DocBlockr for Python

Based off the DocBlockr project, This extension provides the similar funtionality but for python docstrings. The default formatter for this plugin is designed around PEP-257 compliance but with more verbosity: Added variable types, listing class extensions, and listing decorators. The main goal of this project is to help developer provide better documentation by giving easy and consistent formatting.

Installation

Package Control Now you can install it with package control!

  1. Open your command pallete and type Package Control: Install Package.
  2. Find this project DocBlockr Python and press Enter.

Manually Download the release and put it in your installed packages directory yourself

  1. Go to the Latest Release and download the docblockr_python.sublime-package file.
  2. Move this file to your Installed Packages directory. (Preferences > Browse Packages... and go up one directory to see Installed Packages)
  3. If you are updating your existing install, a restart of Sublime Text will be in order.

Usage

There isn't a command pallete command to start this plugin, it is triggerg by hitting enter or tab after opening a docstring (""") at the module, class, or function level. If you wanted to simply put a new line after opening a docstring and not trigger the formatter, just hold ctrl and press enter.

Default and User Settings

You can configure which docstring format to use by updating your user settings for this package. (Preferences > Package Settings > DocBlockr Python > Settings (User)) For a full list of settings with documentation on what they affect, look at the Settings (Default) file.

Project Settings

You can also override your user settings on a per project basis by editing your project file. Any setting will be available for overriding here.

{
    "DocblockrPython": {
        "formatter": "sphinx"
    },
    "folders": [
      // ...
    ]
}

Supported Docstring Styles

Extendability

If you don't like the formatting styles above, or want to make your own style to fit your use case, you can write your own formatter. All you will need to do is extend the Base formatter class and write your formatter functions. If you're not sure about it, you can take a look at any of the other formatters in the formatters source dir and see how they did it.

from DocBlockr_Python.formatters.base import Base


class MyFormatter(Base):
    # This will be used as your settings file value,
    # and how the formatter is registered in the registry
    name = 'my'

Note: The console should yell at you if you didn't write all the abstract methods. Be sure to read the docs on the Base formatter to make sure you understand all the caveats of each formatter function.

Known Issues

  • Only detects closed docstring if it is on a line of the same indentation, and has no text in front of it. Single Line docstrings are converted to block

Roadmap

Things I want to do wtih this project. Not necessarily an exhaustive or prioritized list.

  • Unit Tests!
  • More completions!
  • Javadoc style formatter
  • Keyboard Shortcuts
  • Reparsing Docstring (switch templating style)
  • Command Pallete Commands for changing syntax
  • Dynamic completions based on chosen syntax
  • Integration back with the original DocBlockr
  • Better Syntax Highlighting within docstrings (in particular for other styles)
  • Examples of each style to completion
  • Documentation (isn't it ironic?)