adambullmer / sublime_docblockr_python Goto Github PK

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

License: MIT License

Python 100.00%

python docstrings docblockr sublime-text-3 sublime-text-plugin

sublime_docblockr_python's Introduction

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 press Enter.

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 see Installed 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
Google
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:

ln -s <absolute/path/to/github/repo/sublime_docblockr_python> $HOME/.config/sublime-text-3/Packages/Docblockr_Python

There are no runtime dependencies
Pay attention to the sublime console ctrl + `

Testing Changes

In addition to the setup instructions above, testing will require additinoal setup.

System Requirements:

pyenv
pipenv

Setup:

Install depedencies through pipenv pipenv install --dev
Run unit tests pipenv run tox
- py.test unit tests
- flake8 linting
- pydocstyle (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?)

sublime_docblockr_python's People

Contributors

Stargazers

Watchers

Forkers

marks-chan hdp1213 edsterg byaka misramayank lingjiekong thep0y jordaneremieff botranvan rebeccabulltxt

sublime_docblockr_python's Issues

Python Extended extends bug

With the default Python language enabled, you get the following in formatters/base.py:

But with Python Extended it looks like this:

It is caused by

Extends:
    ABCMeta

And it looks like it is supposed to without that:

parser breaks when square brackets in default value

def foo(bar=[0, 0]):
    return bar

results in

    """[summary]
    
    [description]
    :param 0]: [description]
    :type 0]: [type]
    :param bar: [description], defaults to [0
    :type bar: list, optional
    :returns: [description]
    :rtype: {[type]}
    ""

the expected result is

    """[summary]
    
    [description]
    :param bar: [description], defaults to [0, 0]
    :type bar: list, optional
    :returns: [description]
    :rtype: {[type]}
    """

doesn't work with return type hinting

This breaks auto generated docstring templates:

def foo(bar) -> str:
    return bar

it results in:

    """[summary]
    
    [description]
    """

it should at least parse the parameters and detect that the function returns:

    """[summary]
    
    [description]
    :param bar: [description]
    :type bar: [type]
    :returns: [description]
    :rtype: {[type]}
    """

and ideally it would auto file the return type:

    """[summary]
    
    [description]
    :param bar: [description]
    :type bar: [type]
    :returns: [description]
    :rtype: str
    """

Handle duplicates of Exceptions

Handle multiple same exceptions and generate documentation for unique only.

Example:

def foo(arg1, arg2):
    raise FooError
    raise FooException
    raise FooError
    return False

Actual result:

"""[summary]

[description]

Args:
    arg1: [description]
    arg2: [description]

Returns:
    [description]
    bool

Raises:
    FooError: [description]
    FooException: [description]
    FooError: [description]
"""

Expected result:

"""[summary]

[description]

Args:
    arg1: [description]
    arg2: [description]

Returns:
    [description]
    bool

Raises:
    FooError: [description]
    FooException: [description]
"""

Suuport MagicPython?

Doesn't seem to work using MagicPython syntax highlighter. Could you add this functionality?

Can't work in ST4

Nothing happens after pressing enter. No line breaks.

Creates docstrings with whitespaces in numpty

When creating docstrings from scratch using """ + enter under a function for example, the docstring created has whitespaces between [summary] and [description] and [description] and Returns, any way i can fix that?

First line description

For the Google style guide, the first line in the docstring is used for a summary. PEP0257 also does this together with some if not all of the others. It would be great if this also was supported.

Expected generated docstring:

def foo(bar):
    """[summary]
    
    [description]
    
    Args:
        bar: [description]
    """

Actual generated docstring:

def foo(bar):
    """
    
    [description]
    
    Args:
        bar: [description]
    """

Perhaps it could simply be replaced by the following because not all of the functions require a full description.

def foo(bar):
    """[description]
    
    Args:
        bar: [description]
    """

Unexpected behavior at the end of docstring

How to reproduce

_ denotes the cursor location.

def f(a):
    """_

Now type <Enter>. It becomes:

def f(a):
    """[summary]
    
    [description]
    :param a: [description]
    :type a: [type]
    """

Now [summary] is selected. Typing <Tab> four times, the cursor should jump to:

def f(a):
    """[summary]
    
    [description]
    :param a: [description]
    :type a: [type]
    """_

To continue writing, one would type <Enter>. However, it renders:

def f(a):
    """[summary]
    
    [description]
    :param a: [description]
    :type a: [type]
    """[summary]
    
    [description]
    :param a: [description]
    :type a: [type]
    """

with the second [summary] selected.

Expected behavior

The last <Enter> in the previous example should trigger only an "Enter" rather than insert another block of docstring.

Current workaround

Type Ctrl-<Enter> instead. However, this seems awkward as it breaks normal workflow.

Version and formatter

Sublime text 3: Sublime Text Build 3200
DocBlockr_Python: unknown, but I installed it today (2019-03-15 [YYYY-mm-dd])
formatter: sphinx

Thanks.

doesn't work with argument type hinting

Here's an example that breaks auto generated docstring templates:

def foo(bar: str):
    pass

the result is:

    """[summary]

    [description]
    :param bar: str: [description]
    :type bar: str: [type]
    """

it should at least parse the name correctly:

    """[summary]

    [description]
    :param bar: [description]
    :type bar: [type]
    """

and ideally it would auto file the type:

    """[summary]

    [description]
    :param bar: [description]
    :type bar: str
    """

Not working with MagicPython syntax

I am using MagicPython (https://github.com/MagicStack/MagicPython) as syntax highlighting for Python code in Sublime Text 3.

It seems that DockBlockr_Python does not work in this case — it does not create the doc blocks after opening the doc string and pressing Tab.

What could be done to make it work with this other (or any arbitrary) syntax?

I did a fresh install of build 3126 and installed this and it doesn't seem to be working.

Are you aware of this?

Update docstring

When the first version of a function takes some parameters, it generates the right docstring, that we just have to complete.
However, if we change the function by adding/removing parameter(s), and adding/removing a return, the docstring is not automatically updated.
The only solutions I found are:

either complete by myself, following the format generated
Problem: must know the format rules (which is supposed to be simplified by using docblockr_python). For example, if there was no return in the function when we first generated the docstring, and now there is one, we have to check the format to know how to add our return value with its type and description.
or re-generate docstring, and then copy all descriptions/types of all parameters I already filled before
Problem: time consuming... We are kind of writing the docstring twice...

It would be great if we could update the current docstring.

For now, hitting 'tab' after the starting """ generates a docstring.

What would be great:

When hitting 'tab', when there is already a docstring, generate an updated version of it (or do not change if nothing changed in function parameters/return of course...)
If a parameter is already in the docstring, then do nothing.
Otherwise, add it with default "description"/"type".

Do you think this could be possible?

Thanks

cls argument is ignored even if it's not the first argument.

Current behaviour:

def import_base(self, cls, base):
    """[summary]
    
    [description]
    
    Args:
        base: [description]
    
    Returns:
        [description]
        [type]
    """

Expected behaviour:

def import_base(self, cls, base):
    """[summary]
    
    [description]
    
    Args:
        cls: [description]
        base: [description]
    
    Returns:
        [description]
        [type]
    """

The second argument doesn't refer to the class and should therefore not be ignored as it is a required argument and requires documenting. It's a minor thing, but I thought I'd report it.

***<Enter> trigger does nothing

When I press Enter after typing ***, nothing happens. Even, the cursor remains static i.e. it does not move at all.

My Sublime Text 3 Build is 3126

Here is Sublime Console Log

Traceback (most recent call last):
File "/opt/sublime_text/sublime_plugin.py", line 818, in run
return self.run(edit)
File "commands in /home/mypc/.config/sublime-text-3/Installed Packages/DocBlockr_Python.sublime-package", line 98, in run
File "parsers.parser in /home/mypc/.config/sublime-text-3/Installed Packages/DocBlockr_Python.sublime-package", line 375, in parse
File "parsers.parser in /home/mypc/.config/sublime-text-3/Installed Packages/DocBlockr_Python.sublime-package", line 507, in process_class
File "parsers.parser in /home/mypc/.config/sublime-text-3/Installed Packages/DocBlockr_Python.sublime-package", line 431, in parse_variables
File "parsers.parser in /home/mypc/.config/sublime-text-3/Installed Packages/DocBlockr_Python.sublime-package", line 409, in process_variable
File "parsers.parser in /home/mypc/.config/sublime-text-3/Installed Packages/DocBlockr_Python.sublime-package", line 175, in guess_type_from_value
IndexError: string index out of range_

Multiline signatures are not detected

Having a method signature go over multiple lines does not make it automatically generate the arguments.

This is how a multiline signature is generated:

def test(self, a,
         b):
    """[summary]

    [description]
    """

This is how it should be:

def test(self, a,
         b):
    """[summary]

    [description]

    Args:
        a ([type]): [description]
        b ([type]): [description]
    """

Note: I'm using a custom formatter, a better version of the Google formatter. I plan to make a PR when I have spent some time with it. The changes only really are the added ([type]) and (:obj:[type], optional) for named arguments. It also doesn't have the standard way of defining a default value.

Stopped working with ST3 build 3110

My sublime text just upgraded to build 3110 and I can no longer automatically create docstrings for any Python functions/classes. Pressing Enter after """ does nothing.

Stopped working. Enter does not give docstring anymore

This plugin stopped working. Hitting enter after """ does not result in a docstring anymore

doesn't work when return statement followed by string literal

The following function:

def foo(bar):
    return "hello" + bar

results in:

    """[summary]
    
    [description]
    :param bar: [description]
    :type bar: [type]
    """

should be:

    """[summary]
    
    [description]
    :param bar: [description]
    :type bar: [type]
    :returns: [description]
    :rtype: {[type]}
    """

Creates docstrings of functions with multi-line parameters

For functions with multi-line parameters, docblockr cannot recognize parameters and generates only [summary] and [description] as the picture shows.
After moving ): back by 4 or more spaces, it shows the parameter field but triggers PEP8 E123/125/126

Custom Settings don't work

Hello, thank your for sharing this! 👍

I'm on ST3 Build 3114 and I've tried to "Preferences/ Package Settings/ DockBlockr Python/ Settings Default " but it seems to be empty or the file is not found. In fact in the console I can see

Unable to open /Users/myUser/Library/Application Support/Sublime Text 3/Packages/docblockr_python/DocblockrPython.sublime-settings

Then I've created a file inside my User folder DocblockrPython.sublime-settings whit these settings:

{
    "DocblockrPython": {
        "formatter": "sphinx"
    }
}

But no matter what the formatters don't change.

Where to put custom formatter?

Hi. I want to use sphinx formatter but I don't want the :type param: ..., :rtype: ..., etc., since I already put these info in type annotations. Therefore, I write my own formatter based on SphinxFormatter. However, I now have no idea where to place the new formatter so that the current install of DocBlockr_Python should recognize it. Thanks for any suggestion.

Variables from other classes being fetched

I ran into the following issue:

If there are several classes in the current file, triggering DocBlockr in a class will gather variables from the classes below it.