DocBlockr_Python
Sublime Text DocBlockr for python. Simplifies writing docstring comments in Python.
Details
Installs
- Total 45K
- Win 29K
- Mac 8K
- Linux 8K
Jan 23 | Jan 22 | Jan 21 | Jan 20 | Jan 19 | Jan 18 | Jan 17 | Jan 16 | Jan 15 | Jan 14 | Jan 13 | Jan 12 | Jan 11 | Jan 10 | Jan 9 | Jan 8 | Jan 7 | Jan 6 | Jan 5 | Jan 4 | Jan 3 | Jan 2 | Jan 1 | Dec 31 | Dec 30 | Dec 29 | Dec 28 | Dec 27 | Dec 26 | Dec 25 | Dec 24 | Dec 23 | Dec 22 | Dec 21 | Dec 20 | Dec 19 | Dec 18 | Dec 17 | Dec 16 | Dec 15 | Dec 14 | Dec 13 | Dec 12 | Dec 11 | Dec 10 | Dec 9 | |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Windows | 9 | 7 | 9 | 0 | 4 | 8 | 3 | 8 | 4 | 5 | 4 | 9 | 5 | 9 | 6 | 4 | 6 | 10 | 5 | 10 | 11 | 5 | 5 | 6 | 10 | 3 | 7 | 6 | 4 | 9 | 4 | 7 | 4 | 3 | 2 | 3 | 13 | 3 | 4 | 3 | 5 | 1 | 3 | 5 | 12 | 6 |
Mac | 0 | 2 | 1 | 0 | 1 | 3 | 2 | 2 | 0 | 0 | 0 | 0 | 1 | 2 | 3 | 4 | 1 | 1 | 3 | 0 | 1 | 1 | 0 | 3 | 2 | 2 | 2 | 2 | 1 | 3 | 3 | 2 | 1 | 1 | 1 | 4 | 2 | 1 | 3 | 0 | 2 | 1 | 0 | 1 | 4 | 1 |
Linux | 2 | 0 | 4 | 2 | 0 | 3 | 1 | 1 | 2 | 0 | 2 | 5 | 1 | 2 | 1 | 4 | 2 | 3 | 2 | 2 | 0 | 2 | 0 | 0 | 0 | 1 | 2 | 1 | 2 | 1 | 1 | 1 | 2 | 1 | 5 | 0 | 3 | 3 | 0 | 1 | 0 | 1 | 2 | 0 | 4 | 1 |
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!
- Open your command pallete and type
Package Control: Install Package
. - Find this project
DocBlockr Python
and pressEnter
.
Manually Download the release and put it in your installed packages directory yourself
- Go to the Latest Release and download the
docblockr_python.sublime-package
file. - Move this file to your
Installed Packages
directory. (Preferences > Browse Packages...
and go up one directory to seeInstalled Packages
) - 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
- Docblockr (PEP0257 with types)
- PEP0257
- Numpy
- Sphinx (reST)
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.
Local Development
Below are the instructions to work on this repo locally.
- Clone the repo.
- Uninstall the plugin from sublime text.
- Symlink the github repo into your sublime text packages directory.
- Debian example: “bash ln -s $HOME/.config/sublime-text-3/Packages/Docblockr_Python
1. There are no runtime dependencies
1. Pay attention to the sublime console ```ctrl + ` ```
Testing Changes
---------------
In addition to the setup instructions above, testing will require additinoal setup.
**System Requirements:**
- [pyenv](https://github.com/pyenv/pyenv)
- [pipenv](https://pipenv.readthedocs.io/en/latest/)
**Setup:**
1. Install depedencies through pipenv `pipenv install --dev`
1. Run unit tests `pipenv run tox`
- [py.test](https://docs.pytest.org/en/latest/) unit tests
- [flake8](http://flake8.pycqa.org/en/latest/) linting
- [pydocstyle](http://www.pydocstyle.org/en/2.1.1/) (formerly PEP257) docstring checker
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
- The tests run in python `3.4.3`, however sublime's python version is `3.3.6`. This is due to the difficulty of getting a working version of 3.3.6 in a dev environment, and the differences should be minimal.
Roadmap
-------
Things I want to do wtih this project. Not necessarily an exhaustive or prioritized list.
- Unit Tests!
- Needs a test harness of some sort for sublime internals.
- CI, probably circleci
- Coverage reporting
- 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?)