spadarian / docblock-python Goto Github PK

View Code? Open in Web Editor NEW

22.0 22.0 8.0 4.11 MB

Atom plugin to insert documentation blocks for python functions

License: GNU General Public License v2.0

JavaScript 99.50% Less 0.50%

atom documentation python

docblock-python's People

Contributors

Stargazers

Watchers

Forkers

piccolbo willbowditch skalt julienpeloton pararhyme gonzalezzfelipe gaelicgrime

docblock-python's Issues

The last update 0.17.3 has conflicts with other packages

OS: Ubuntu 18.04
Editor: Atom 1.43.0
Node: v10.11.0
docblock-python: 0.17.3
docblock-python settings: all set to default, none is changed.
Minimap: 4.29.9
Minimap setting: all set to default, none is changed.

I opened Atom, everything is working as usual. I got a notification that docblock-python needs to be updated, I updated the package and restarted Atom, but I was surprised that minimap does not work anymore!
I uninstalled minimap and reinstalled it again, uninstalled Atom, removed the configs, and installed atom and minimap all along with docblock-python. However minimap still not working.
I uninstalled docblock-python, minimap is showing again!

I think the last update had messed something, please check it.
Thank you.

Cython support

This is an awesome extension!

It would be really nice, if Cython would be supported, where even more information can be automatically casted into the docstring, since sometimes statically typed function definitions are used.

But as a starting point it would be really helpful, if at least Cython would be allowed by extending the accepted starting keywords with 'cdef' and 'cpdef'.

Missing class docstring formats in Google, Numpy styles

The numpy style guide prescribes something like

class Photo(ndarray):
    """
    Array with associated photographic information.

    ...

    Attributes
    ----------
    height             # has its own docstring
    exposure : float
        Exposure in seconds.

    Methods          # optional, since they have their own docstrings
    -------
    colorspace(c='rgb')
        Represent the photo in the given colorspace.
    gamma(n=1.0)
        Change the photo's gamma exposure.

and the google style guides requires the form

class SampleClass(object):
    """Summary of class here.

    Longer class information....
    Longer class information....

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    def __init__(self, likes_spam=False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""

This package should be capable of templating these class docstrings.

Add a checkbox option to separate param description and type

This specific for Sphinx style. See #25 for details.

No Generation happening in Cython

I get no output from docblock in a file named foobar.pyx, which is residing in a class definition. I am running docblock 0.11, atom 1.32.2 and electron 2.0.12 on Manjaro Linux.

Hints?

cpdef tuple _getComplexity(self):
        cdef float complexityFwd = self.numRows
        cdef float complexityBwd = self.numCols
        cdef Matrix item
        for item in self:
            complexityFwd += item.numRows + item.numCols
            complexityBwd += item.numCols + item.numRows

        return (complexityFwd, complexityBwd)

Wrong output for 'generate_docblock' for python

Generate_docblock generates form python code

class BelScript:
    def __init__(self):
        self.a=1

... this ...

class BelScript:
    """Short summary.
null    a

    """
    def __init__(self):
        self.a=1

By the way thanks for this useful package

Wrong indentation of sphinx style :return: and :raises:

docblock-python is really helpful, many thanks to spadarian!

I have a problem with indentation: if I choose style "sphinx" (and all checkboxes enabled) the lines with :return: are not indented at all, and :raises: are always indented 4 spaces, even if the doc comment starts more indented. The rest of the lines are ok.

Example: docblock-bug_sphinx-indent.txt

I tried to fix it by editing lib/templates.js, but did not succeed yet.
Am I doing something wrong? Or is it a bug?

I use atom 1.40.1 and docblock 0.15.0.

Uncaught TypeError: Cannot read property 'map' of null

Generate_docblock works for

class Test:
    def __init__(self, a):
        pass

but not for default value in init

class Test:
    def __init__(self, a=1):
        pass

Atom: 1.25.1 x64
Electron: 1.7.11
OS: Ubuntu 16.04.4
Thrown From: docblock-python package 0.5.0

Stack Trace

Uncaught TypeError: Cannot read property 'map' of null

At /home/ceb/.atom/packages/docblock-python/lib/docblock-python.js:320

TypeError: Cannot read property 'map' of null
    at Object.process_class (/packages/docblock-python/lib/docblock-python.js:320:28)
    at /packages/docblock-python/lib/docblock-python.js:142:35
    at Object.generate_docblock (/packages/docblock-python/lib/docblock-python.js:155:13)
    at HTMLElement.docblockPythonGenerate_docblock (/packages/docblock-python/lib/docblock-python.js:81:55)
    at CommandRegistry.handleCommandEvent (/usr/share/atom/resources/app/src/command-registry.js:384:49)
    at KeymapManager.module.exports.KeymapManager.dispatchCommandEvent (/usr/share/atom/resources/app/node_modules/atom-keymap/lib/keymap-manager.js:621:22)
    at KeymapManager.module.exports.KeymapManager.handleKeyboardEvent (/usr/share/atom/resources/app/node_modules/atom-keymap/lib/keymap-manager.js:412:28)
    at WindowEventHandler.handleDocumentKeyEvent (/usr/share/atom/resources/app/src/window-event-handler.js:110:40)

Commands

     -0:51.7.0 atom-updater-linux:check (input.hidden-input)
     -0:40.9.0 docblock-python:generate_docblock (input.hidden-input)

Non-Core Packages

atom-csv-markdown 1.0.2 
atom-html-preview 0.2.5 
atom-latex 0.8.4 
atom-python-run 0.9.6 
atom-updater-linux 1.1.2 
autocomplete 0.47.0 
autocomplete-boilerplate 0.2.0 
autocomplete-python 1.10.5 
browser-plus 0.0.98 
docblock-python 0.5.0 
file-icons 2.1.18 
gitlab-integration 0.4.7 
Hydrogen 2.4.1 
import 1.7.0 
language-bel 0.1.0 
language-latex 1.1.1 
language-restructuredtext 1.1.2 
latex 0.50.0 
markdown-pdf 2.1.0 
markdown-preview-enhanced 0.15.6 
markdown-toc 0.4.2 
open-unsupported-files 1.0.20 
pandoc-convert 1.1.1 
platformio-ide-terminal 2.8.1 
python-autopep8 0.1.3 
python-tools 0.6.9 
quick-query 0.12.4 
quick-query-sqlite 0.3.1 
rst-preview 1.3.1 
rst-preview-pandoc 0.1.12 
script 3.17.3 
tablr 1.8.3 
todo-show 2.3.0

Uncaught RangeError: Maximum call stack size exceeded

[Enter steps to reproduce:]

I just tried to create a class docstring from the menu of right click. It froze!!!

Atom: 1.32.0 x64
Electron: 2.0.9
OS: Mac OS X 10.12.6
Thrown From: docblock-python package 0.10.0

Stack Trace

Uncaught RangeError: Maximum call stack size exceeded

At /Users/himavarsha/.atom/packages/docblock-python/lib/docblock-python.js:327

RangeError: Maximum call stack size exceeded
    at /packages/docblock-python/lib/docblock-python.js:327:14
    at Object.find_init (/packages/docblock-python/lib/docblock-python.js:345:9)
    at /packages/docblock-python/lib/docblock-python.js:340:22
    at Object.find_init (/packages/docblock-python/lib/docblock-python.js:345:9)
    at /packages/docblock-python/lib/docblock-python.js:340:22
    at Object.find_init (/packages/docblock-python/lib/docblock-python.js:345:9)
    at /packages/docblock-python/lib/docblock-python.js:340:22
    at Object.find_init (/packages/docblock-python/lib/docblock-python.js:345:9)
    at /packages/docblock-python/lib/docblock-python.js:340:22
    at Object.find_init (/packages/docblock-python/lib/docblock-python.js:345:9)
    at /packages/docblock-python/lib/docblock-python.js:340:22
    at Object.find_init (/packages/docblock-python/lib/docblock-python.js:345:9)
    at /packages/docblock-python/lib/docblock-python.js:340:22
    at Object.find_init (/packages/docblock-python/lib/docblock-python.js:345:9)
    at /packages/docblock-python/lib/docblock-python.js:340:22
    at Object.find_init (/packages/docblock-python/lib/docblock-python.js:345:9)
    at /packages/docblock-python/lib/docblock-python.js:340:22
    at Object.find_init (/packages/docblock-python/lib/docblock-python.js:345:9)
    at /packages/docblock-python/lib/docblock-python.js:340:22
    at Object.find_init (/packages/docblock-python/lib/docblock-python.js:345:9)
    at /packages/docblock-python/lib/docblock-python.js:340:22
    at Object.find_init (/packages/docblock-python/lib/docblock-python.js:345:9)
    at /packages/docblock-python/lib/docblock-python.js:340:22
    at Object.find_init (/packages/docblock-python/lib/docblock-python.js:345:9)
    at /packages/docblock-python/lib/docblock-python.js:340:22
    at Object.find_init (/packages/docblock-python/lib/docblock-python.js:345:9)
    at /packages/docblock-python/lib/docblock-python.js:340:22
    at Object.find_init (/packages/docblock-python/lib/docblock-python.js:345:9)
    at /packages/docblock-python/lib/docblock-python.js:340:22
    at Object.find_init (/packages/docblock-python/lib/docblock-python.js:345:9)

Commands

     -0:18.9.0 core:close (atom-pane.pane.active)
     -0:08.0 docblock-python:generate_docblock (span.syntax--entity.syntax--name.syntax--type.syntax--class)

Non-Core Packages

atom-django 0.3.2 
autocomplete-python 1.10.9 
busy-signal 1.4.3 
docblock-python 0.10.0 
docker 0.8.0 
Hydrogen 2.5.1 
intentions 1.1.5 
linter 2.0.0 
linter-pylint 2.1.1 
linter-ui-default 1.7.1 
merge-conflicts 1.4.5 
platformio-ide-terminal 2.8.4 
python-indent 1.1.5 
python-isort 0.0.7 
react 0.18.0 
script 3.18.1 
teletype 0.13.3

Uncaught TypeError: Cannot read property '0' of null

[Enter steps to reproduce:]

Create a new Python function whose argument list extends over two or more lines
Invoke docblock-python on the line containing the function name to generate docstring

Atom: 1.29.0 x64
Electron: 2.0.5
OS: Microsoft Windows 10 Pro
Thrown From: docblock-python package 0.9.1

Stack Trace

Uncaught TypeError: Cannot read property '0' of null

At C:\Users\sdwil\.atom\packages\docblock-python\lib\docblock-python.js:260

TypeError: Cannot read property '0' of null
    at Object.process_def (/packages/docblock-python/lib/docblock-python.js:260:36)
    at /packages/docblock-python/lib/docblock-python.js:189:45
    at Array.map (<anonymous>)
    at /packages/docblock-python/lib/docblock-python.js:163:14
    at Object.generate_docblock (/packages/docblock-python/lib/docblock-python.js:227:12)
    at HTMLElement.docblockPythonGenerate_docblock (/packages/docblock-python/lib/docblock-python.js:107:55)
    at CommandRegistry.handleCommandEvent (~/AppData/Local/atom/app-1.29.0/resources/app/src/command-registry.js:384:49)
    at KeymapManager.module.exports.KeymapManager.dispatchCommandEvent (~/AppData/Local/atom/app-1.29.0/resources/app/node_modules/atom-keymap/lib/keymap-manager.js:621:22)
    at KeymapManager.module.exports.KeymapManager.handleKeyboardEvent (~/AppData/Local/atom/app-1.29.0/resources/app/node_modules/atom-keymap/lib/keymap-manager.js:412:28)
    at WindowEventHandler.handleDocumentKeyEvent (~/AppData/Local/atom/app-1.29.0/resources/app/src/window-event-handler.js:110:40)

Commands

     -5:12.7.0 core:select-up (input.hidden-input)
     -5:12.1.0 core:backspace (input.hidden-input)
     -5:11.7.0 editor:newline (input.hidden-input)
  6x -5:08.3.0 editor:delete-to-beginning-of-word (input.hidden-input)
     -0:35.7.0 core:select-all (input.hidden-input)
     -0:21.7.0 core:move-down (input.hidden-input)
     -0:21.6.0 editor:select-to-end-of-word (input.hidden-input)
     -0:20.9.0 core:move-up (input.hidden-input)
     -0:20.6.0 core:move-down (input.hidden-input)
     -0:20.4.0 core:move-right (input.hidden-input)
  2x -0:19.9.0 core:select-up (input.hidden-input)
     -0:19.6.0 editor:select-to-beginning-of-word (input.hidden-input)
     -0:19.2.0 core:backspace (input.hidden-input)
     -0:18 docblock-python:generate_docblock (input.hidden-input)
  2x -0:16.2.0 core:move-up (input.hidden-input)
     -0:14.6.0 docblock-python:generate_docblock (input.hidden-input)

Non-Core Packages

atom-beautify 0.32.5 
atom-ctags 5.1.2 
atom-dark-fusion-syntax 2.2.1 
atom-file-icons 0.6.0 
atom-ide-ui 0.13.0 
atom-material-syntax 1.0.8 
atom-ungit 0.8.0 
block-comment-plus 0.5.1 
code-peek 1.4.21 
default-language 0.3.1 
docblock-python 0.9.1 
duotone-blue-dark-syntax 1.4.0 
duotone-dark-sea-syntax 2.1.0 
duotone-dark-space-syntax 2.1.0 
duotone-dark-syntax 2.1.0 
duotone-light-syntax 2.1.0 
duotone-snow 2.2.0 
electron-light-syntax 1.4.0 
file-icons 2.1.22 
flat-ui-syntax 0.5.1 
fuzzy-theme-switcher 1.0.0 
git-diff-details 1.4.0 
git-plus 8.0.0 
git-time-machine 2.1.0 
hey-pane 1.1.0 
hidpi 0.14.0 
Hydrogen 2.5.1 
hydrogen-launcher 1.2.2 
hydrogen-python 0.0.6 
ide-python 1.0.0 
language-diff 0.7.0 
language-gitignore 0.3.0 
language-latex 1.1.1 
Lucario 2.2.0 
MagicPython 1.0.12 
monokai-one-dark-vivid-syntax 1.6.0 
nord-atom-syntax 0.9.1 
nord-atom-ui 0.11.0 
one-dark-vivid-syntax 1.8.1 
pdf-view 0.70.0 
pen-paper-coffee-syntax 0.17.0 
platformio-ide-terminal 2.8.3 
python-autopep8 0.1.3 
python-indent 1.1.5 
python-tools 0.6.9 
solarized-light-syntax-modified 0.6.2 
spacegray-light-syntax 0.1.0 
split-diff 1.5.2 
theme-switcher 1.1.0

Uncaught TypeError: Cannot read property '1' of null

Steps to Reproduce:

Creating a dock block on a class with empty (incomplete) __init__ generates the error. Write the following code:

class foo():
    def __init__(self, bah)

Generate doc-block (e.g. by selecting the class name, right clicking and then executing Generate DocBlock)

Adding a colon and a pass statement makes it execute correctly.

class foo():
    """Short summary."""
    def __init__(self, bah):
        pass

Atom: 1.54.0 x64
Electron: 6.1.12
OS: Mac OS X 10.15.7
Thrown From: docblock-python package 0.19.1

Stack Trace

Uncaught TypeError: Cannot read property '1' of null

At ~/.atom/packages/docblock-python/lib/docblock-python.js:730

TypeError: Cannot read property '1' of null
    at Object.process_class (/packages/docblock-python/lib/docblock-python.js:730:30)
    at /packages/docblock-python/lib/docblock-python.js:360:29
    at Array.map (<anonymous>)
    at /packages/docblock-python/lib/docblock-python.js:331:12
    at Object.generate_docblock (/packages/docblock-python/lib/docblock-python.js:395:10)
    at HTMLElement.docblockPythonGenerate_docblock (/packages/docblock-python/lib/docblock-python.js:163:53)
    at CommandRegistry.handleCommandEvent (/Applications/Atom.app/Contents/Resources/app/static/<embedded>:11:350382)
    at CommandRegistry.dispatch (/Applications/Atom.app/Contents/Resources/app/static/<embedded>:11:348857)
    at AtomEnvironment.dispatchContextMenuCommand (/Applications/Atom.app/Contents/Resources/app/static/<embedded>:1:727628)
    at EventEmitter.t (/Applications/Atom.app/Contents/Resources/app/static/<embedded>:1:735661)
    at EventEmitter.emit (events.js:200:13)
    at Object.onMessage (/Applications/Atom.app/Contents/Resources/electron.asar/renderer/init.js:42:16)

Commands

     -0:44.2.0 markdown-writer:indent-list-line (input.hidden-input)
     -0:44.2.0 snippets:next-tab-stop (input.hidden-input)
     -0:44.2.0 snippets:expand (input.hidden-input)
     -0:44.2.0 editor:indent (input.hidden-input)
     -0:44 markdown-writer:indent-list-line (input.hidden-input)
     -0:44 snippets:next-tab-stop (input.hidden-input)
     -0:44 snippets:expand (input.hidden-input)
     -0:44 editor:indent (input.hidden-input)
     -0:43.8.0 markdown-writer:indent-list-line (input.hidden-input)
     -0:43.8.0 snippets:next-tab-stop (input.hidden-input)
     -0:43.8.0 snippets:expand (input.hidden-input)
     -0:43.8.0 editor:indent (input.hidden-input)
     -0:40.6.0 editor:delete-to-beginning-of-line (input.hidden-input)
     -0:40.4.0 core:backspace (input.hidden-input)
  2x -0:35.2.0 docblock-python:generate_docblock (span.syntax--source.syntax--python)
     -0:02.0 core:copy (atom-notification.fatal.icon.icon-bug.native-key-bindings.has-detail.has-close.has-stack)

Non-Core Packages

autocomplete-python 1.17.0 
busy-signal 2.0.1 
copy-as-rtf 0.9.3 
docblock-python 0.19.1 
file-icons 2.1.46 
Hydrogen 2.14.7 
intentions 1.1.5 
language-cypher 0.5.0 
language-latex 1.2.0 
linter 3.3.0 
linter-flake8 2.4.0 
linter-ui-default 3.2.3 
markdown-preview-plus 4.9.0 
markdown-themeable-pdf 1.2.1 
markdown-writer 2.11.11 
python-autopep8 0.1.3 
script 3.29.3 
split-diff 1.6.1

Numpy Documentation Link Update

The link you provided is no longer in use, please replace it with https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

I love using your extension, keep up the good work!

Wrong indentation of sphinx style :return: if :rtype: is disabled

If I use "sphinx" Style, enable "Describe returned value" and disable "Show types" then :return: line is always indented 0 spaces. The rest of the sphinx doc block is indented correctly.

I see this bug in doc-block 0.16.0 and in latest 0.18.1.

Automatically run on function creation

I would love if this could automatically run upon completion of a function or class definition. Is this possible?

Many thanks,
Ruaridh

Support for defaults and type hints including commas

docblock-python should consider all of a compound type hint as one type.
Given

from typing import Union 
def foo(bar: Union[int, float] ) -> str:
    return f'{bar}'

the plugin generates

    """Short summary.

    Args:
        bar (Union[int): Description of parameter `bar`.
        float] (type): Description of parameter `float]`.

    Returns:
        str: Description of returned object.

    """

[Feature Request] Single quotes

I'd like to be able to switch to single quoted docstrings.

Generating docblocks from multiple cursors causes a stack overflow

With a document

def foo(x): ...

def bar(y): ...

placing two cursors in both function definitions and calling generate_docblock causes a stack overflow within get_header's recursion.
Generating docstrings for multiple things at once isn't what this package is designed for, but it would be nice to have.

Fix specs to pass Travis tests

At the moment, one of the tests is disabled to pass Travis tests.

It runs fine locally.

The error is raised when loading the linter package.

No idea how to fix this, so any suggestions are more than welcome.

[Linter] Error running docblock-python

If the experimental Lint support is enabled, I receive the titled error from Linter. Screenshot:

I see three errors in the console. First one:

linter-registry.js:145 [Linter] Error running docblock-python TypeError: Cannot read property 'map' of undefined
    at file:///C:/Users/samam/.atom/packages/docblock-python/lib/docblock-python.js:176:38
    at new Promise (<anonymous>)
    at Object.lint (file:///C:/Users/samam/.atom/packages/docblock-python/lib/docblock-python.js:175:14)
    at file:///C:/Users/samam/.atom/packages/linter/lib/linter-registry.js:113:26
    at new Promise (<anonymous>)
    at _loop (file:///C:/Users/samam/.atom/packages/linter/lib/linter-registry.js:111:9)
    at LinterRegistry.<anonymous> (file:///C:/Users/samam/.atom/packages/linter/lib/linter-registry.js:98:40)
    at Generator.next (<anonymous>)
    at LinterRegistry.<anonymous> (file:///C:/Users/samam/.atom/packages/linter/lib/linter-registry.js:178:4)
    at Generator.next (<anonymous>)
    at step (C:\Users\samam\.atom\packages\linter\lib\linter-registry.js:9:273)
    at C:\Users\samam\.atom\packages\linter\lib\linter-registry.js:9:443
    at new Promise (<anonymous>)
    at LinterRegistry.<anonymous> (C:\Users\samam\.atom\packages\linter\lib\linter-registry.js:9:99)
    at file:///C:/Users/samam/.atom/packages/linter/lib/main.js:114:30
    at Function.simpleDispatch (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:1211909)
    at Emitter.emit (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:1213350)
    at EditorLinter.lint (file:///C:/Users/samam/.atom/packages/linter/lib/editor-linter.js:52:18)
    at EditorRegistry.createFromTextEditor (file:///C:/Users/samam/.atom/packages/linter/lib/editor-registry.js:47:20)
    at file:///C:/Users/samam/.atom/packages/linter/lib/editor-registry.js:28:14
    at onDidAddTextEditor (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:428476)
    at Function.simpleDispatch (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:1211909)
    at Emitter.emit (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:1213350)
    at onDidAddPaneItem (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:426579)
    at Function.simpleDispatch (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:1211909)
    at Emitter.emit (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:1213350)
    at PaneContainer.didAddPaneItem (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:446715)
    at Pane.addItem (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:459126)
    at Pane.activateItem (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:457989)
    at Workspace.open (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:431703)
(anonymous) @ linter-registry.js:145

Second one, possibly unrelated:

Error: Cannot decorate a destroyed marker
    at DecorationManager.decorateMarker (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:519423)
    at TextEditor.decorateMarker (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:27540)
    at DatatipManager.mountDataTipWithMarker (C:\Users\samam\.atom\packages\atom-ide-datatip\lib\datatip-manager.js:386:12)
    at DatatipManager.showDataTip (C:\Users\samam\.atom\packages\atom-ide-datatip\lib\datatip-manager.js:325:48)

Third one:

[Linter] Error running docblock-python TypeError: Cannot read property 'map' of undefined
    at file:///C:/Users/samam/.atom/packages/docblock-python/lib/docblock-python.js:176:38
    at new Promise (<anonymous>)
    at Object.lint (file:///C:/Users/samam/.atom/packages/docblock-python/lib/docblock-python.js:175:14)
    at file:///C:/Users/samam/.atom/packages/linter/lib/linter-registry.js:113:26
    at new Promise (<anonymous>)
    at _loop (file:///C:/Users/samam/.atom/packages/linter/lib/linter-registry.js:111:9)
    at LinterRegistry.<anonymous> (file:///C:/Users/samam/.atom/packages/linter/lib/linter-registry.js:98:40)
    at Generator.next (<anonymous>)
    at LinterRegistry.<anonymous> (file:///C:/Users/samam/.atom/packages/linter/lib/linter-registry.js:178:4)
    at Generator.next (<anonymous>)
    at step (C:\Users\samam\.atom\packages\linter\lib\linter-registry.js:9:273)
    at C:\Users\samam\.atom\packages\linter\lib\linter-registry.js:9:443
    at new Promise (<anonymous>)
    at LinterRegistry.<anonymous> (C:\Users\samam\.atom\packages\linter\lib\linter-registry.js:9:99)
    at file:///C:/Users/samam/.atom/packages/linter/lib/main.js:114:30
    at Function.simpleDispatch (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:1211909)
    at Emitter.emit (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:1213350)
    at EditorLinter.lint (file:///C:/Users/samam/.atom/packages/linter/lib/editor-linter.js:52:18)
    at EditorRegistry.createFromTextEditor (file:///C:/Users/samam/.atom/packages/linter/lib/editor-registry.js:47:20)
    at file:///C:/Users/samam/.atom/packages/linter/lib/editor-registry.js:28:14
    at onDidAddTextEditor (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:428476)
    at Function.simpleDispatch (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:1211909)
    at Emitter.emit (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:1213350)
    at onDidAddPaneItem (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:426579)
    at Function.simpleDispatch (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:1211909)
    at Emitter.emit (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:1213350)
    at PaneContainer.didAddPaneItem (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:446715)
    at Pane.addItem (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:459126)
    at Pane.activateItem (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:457989)
    at Workspace.open (C:\Users\samam\AppData\Local\atom\app-1.41.0\resources\app\static\<embedded>:11:431703)

Support for python type hinting

Python3.6.5+ now supports type hinting: https://docs.python.org/3/library/typing.html.
Autogenerated docstrings should include the available information about argument and return types. This means documenting

def greeting(name: str) -> str:
    return 'Hello ' + name

should populate something like name (str): [description] ... returns: (str)[description]

parametrize the tab length

See https://github.com/google/yapf/blob/master/CONTRIBUTING.rst#yapf-coding-style: they use two spaces for indentation rather than four spaces. Grabbing the current editor tab spacing would handle this (admittedly heretical) use-case.

Generally where the change would be made: https://github.com/spadarian/docblock-python/blob/master/lib/docblock-python.js#L296

~~atom.config.scopedSettingsStore.cache['getPropertyValue:.source.python:editor.tabLength'] does grab the correct number of spaces, but there should be a better way to do it.~~
atom.config.get('editor.tabLength') should do the trick.

Linter crashing (TypeError: Cannot read property 'column' of null)

Getting an issue when using the linter. Happy to help debug - below is my console output:

C:\Users\Samuel Troper\.atom\packages\linter\lib\linter-registry.js:154 [Linter] Error running docblock-python TypeError: Cannot read property 'column' of null
    at Object.get_init (file:///C:/Users/Samuel Troper/.atom/packages/docblock-python/lib/docblock-python.js:575:22)
    at Object.get_class_init (file:///C:/Users/Samuel Troper/.atom/packages/docblock-python/lib/linter-docblock-python.js:83:27)
    at file:///C:/Users/Samuel Troper/.atom/packages/docblock-python/lib/linter-docblock-python.js:164:33
    at Array.map (<anonymous>)
    at file:///C:/Users/Samuel Troper/.atom/packages/docblock-python/lib/linter-docblock-python.js:162:17
    at file:///C:/Users/Samuel Troper/.atom/packages/docblock-python/lib/linter-docblock-python.js:176:10
    at Object.lint_docblocks (file:///C:/Users/Samuel Troper/.atom/packages/docblock-python/lib/linter-docblock-python.js:178:38)
    at file:///C:/Users/Samuel Troper/.atom/packages/docblock-python/lib/docblock-python.js:176:22
    at new Promise (<anonymous>)
    at Object.lint (file:///C:/Users/Samuel Troper/.atom/packages/docblock-python/lib/docblock-python.js:175:14)
    at file:///C:/Users/Samuel Troper/.atom/packages/linter/lib/linter-registry.js:113:26
    at new Promise (<anonymous>)
    at _loop (file:///C:/Users/Samuel Troper/.atom/packages/linter/lib/linter-registry.js:111:9)
    at LinterRegistry.<anonymous> (file:///C:/Users/Samuel Troper/.atom/packages/linter/lib/linter-registry.js:98:40)
    at Generator.next (<anonymous>)
    at LinterRegistry.<anonymous> (file:///C:/Users/Samuel Troper/.atom/packages/linter/lib/linter-registry.js:178:4)
    at Generator.next (<anonymous>)
    at step (C:\Users\Samuel Troper\.atom\packages\linter\lib\linter-registry.js:9:273)
    at C:\Users\Samuel Troper\.atom\packages\linter\lib\linter-registry.js:9:443
    at new Promise (<anonymous>)
    at LinterRegistry.<anonymous> (C:\Users\Samuel Troper\.atom\packages\linter\lib\linter-registry.js:9:99)
    at file:///C:/Users/Samuel Troper/.atom/packages/linter/lib/main.js:114:30
    at Function.simpleDispatch (C:\Users\Samuel Troper\AppData\Local\atom\app-1.40.1\resources\app\static\<embedded>:11:1209208)
    at Emitter.emit (C:\Users\Samuel Troper\AppData\Local\atom\app-1.40.1\resources\app\static\<embedded>:11:1210649)
    at EditorLinter.lint (file:///C:/Users/Samuel Troper/.atom/packages/linter/lib/editor-linter.js:52:18)
    at EditorRegistry.createFromTextEditor (file:///C:/Users/Samuel Troper/.atom/packages/linter/lib/editor-registry.js:47:20)
    at file:///C:/Users/Samuel Troper/.atom/packages/linter/lib/editor-registry.js:28:14
    at Workspace.observeTextEditors (C:\Users\Samuel Troper\AppData\Local\atom\app-1.40.1\resources\app\static\<embedded>:11:428138)
    at EditorRegistry.activate (file:///C:/Users/Samuel Troper/.atom/packages/linter/lib/editor-registry.js:27:22)
    at Linter.registryEditorsInit (file:///C:/Users/Samuel Troper/.atom/packages/linter/lib/main.js:124:26)
(anonymous) @ C:\Users\Samuel Troper\.atom\packages\linter\lib\linter-registry.js:154

New docblock 0.17 defeats minimap

I have installed Atom 1.44.0 and minimap 4.29.9. When I install docblock-python 0.17.3 then minimap won't show up anymore. Toggling minimap off and on again shows an error on developer console, see below!

I does not help to disable suspicious settings of both packages. But if I disable docblock, restart Atom and enable it again, then both packages work as expected and even toggling minimap works without error. So I think there is a problem during startup, maybe some concurrent dependencies?

11:39:25.803 /home/oliver/.atom/packages/minimap/lib/main.js:394 Uncaught TypeError: minimapElement.attach is not a function
    at subscriptions.add.atom.workspace.observeTextEditors (/home/oliver/.atom/packages/minimap/lib/main.js:394)
    at Workspace.observeTextEditors (/usr/share/atom/resources/app/static/<embedded>:11)
    at Main.initSubscriptions (/home/oliver/.atom/packages/minimap/lib/main.js:389)
    at Main.toggle (/home/oliver/.atom/packages/minimap/lib/main.js:184)
    at HTMLElement.minimap:toggle (/home/oliver/.atom/packages/minimap/lib/main.js:98)
    at CommandRegistry.handleCommandEvent (/usr/share/atom/resources/app/static/<embedded>:11)
    at CommandRegistry.dispatch (/usr/share/atom/resources/app/static/<embedded>:11)
    at AtomEnvironment.dispatchApplicationMenuCommand (/usr/share/atom/resources/app/static/<embedded>:1)
    at EventEmitter.t (/usr/share/atom/resources/app/static/<embedded>:1)
    at EventEmitter.emit (events.js:182)
subscriptions.add.atom.workspace.observeTextEditors @ /home/oliver/.atom/packages/minimap/lib/main.js:394
observeTextEditors @ <embedded>:11
initSubscriptions @ /home/oliver/.atom/packages/minimap/lib/main.js:389
toggle @ /home/oliver/.atom/packages/minimap/lib/main.js:184
minimap:toggle @ /home/oliver/.atom/packages/minimap/lib/main.js:98
handleCommandEvent @ <embedded>:11
dispatch @ <embedded>:11
dispatchApplicationMenuCommand @ <embedded>:1
t @ <embedded>:1
emit @ events.js:182

Repeated attribute when using if statement in init function

Example:

...
def __init__(self, a):
    if a > 0:
        self.positive = True
    else:
        self.positive = False

That would add the attribute twice.

Tab through arguments

Hey Jose,

first of all, thank you so much for doing this. That's the one thing I've been missing after moving from vim to atom.

It would be great if one can tab through the arguments like you can do in https://atom.io/packages/docblockr or UltiSnips, but I have no idea how hard it would be to implement this.

Support Sphinx docstyle

As described here: http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists

[Feature Request] - purpose a template

Hi there !

Thanks for the work on this module that simplifies working on documenting code !

My request is to be allowed to fine tune the default template or purpose some settings options for some parts of the default template.

For instance, I personaly prefer to write "description of this arg. Defaults to XXX" instead of your "(the default is XXXX)."

I also want to let the parameter names being generated with backquotes, as this is interpreted by atom and shown on hover popup with different formatting.

This is more eye catching while reading code :)

Best regards ;)

Don't include type in docblock

The commonly used sphinx extension napoleon allows for types to be documented from type annotations without the need to specify types in the docstring.
https://sphinxcontrib-napoleon.readthedocs.io/en/latest/#type-annotations

It would convenient if there was an option to prevent adding the type.

Example

def my_func(arg1: str, arg2: int) -> str:
    """Short summary.

    Args:
        arg1: Description of parameter `arg1`.
        arg2: Description of parameter `arg2`.

    Returns:
        Description of returned object.
    """
    return arg1 * arg2

Instead of ...

def my_func(arg1: str, arg2: int) -> str:
    """Short summary.

    Args:
        arg1 (str): Description of parameter `arg1`.
        arg2 (int): Description of parameter `arg2`.

    Returns:
        str: Description of returned object.
    """
    return arg1 * arg2

In my limited experience type hinting arguments is more common than annotating the return types.

Support async definitions

As of python 3.5, the language includes the syntax async def (source). This is (1) awesome and (2) not yet supported by docblock-python.

Not working on mac os high sierra

Hi there,

Fantastic idea and was looking forward to using it but it doesn't appear to be working on High Sierra. Every time I select Generate DocBlock on my function it just highlights the function name and that's it - any idea what's going on? Really want to use this!

Problem with lint and multiple cursors

The lint option is disabled by default so it shouldn't affect most users.

If you face this problem, please disable the "Enable lint to show missing documentation (experimental)" option.

I will fix this as soon as I have some time.

[Feature request] Add keybinding to switch between styles

I use this package with different projects that use different docstring styles, and it is really slow to have to open the package config to switch between them. It would be awesome to have a keybinding that opens a prompt to change the style.

issue generating docblock when class doesn't have init() fn

Hello,

first of all, thanks for a very fine atom package!

I've noticed the following issue, when a python class is missing a __init__() fn. In the following example I've generated docblock in the same way for both classes. The first one was generated correctly according to my settings:

class AA:
    '''Short summary.

    Attributes
    ----------
    attr1 : type
        Description of attribute `attr1`.
    attr2 : type
        Description of attribute `attr2`.

    '''
    attr1 = 1
    attr2 = 2

    def __init__(self):
        return True

    def f1(self):
        return True


class BB:
    """Short summary."""
    attr1 = 1
    attr2 = 2

    def f1(self):
        return True

Adopt eslint

I was looking into another issue and noticed this project does not use eslint. Adopting a linter would make contributing to this project easier by making the code more consistent and giving a clear set of rules to follow. I'd vote using eslint-config-google and having husky enforce pre-commit linting/error correction. @spadarian, let me know which rules you want and I'll set it up!

[Feature request] Add a feature to blank out the default description

First of all, thanks for the extension I like the core idea. However during use I find myself having to do "too much work" to remove the default parameter description, I therefore propose to add an option to leave the link blank after the parameter type "Description of variable `whatever'". Specifically change:

def f(x = None) -> None:
    """Short summary.

    :param x: Description of parameter `x`. Defaults to None.
    :return: Description of returned object.

    """
    return x

To:

def f(x = None) -> None:
    """Short summary.

    :param x: . Defaults to None.
    :return:

    """
    return x

Edit: I tried playing around with the source js script but for some reason, it doesn't stick, I'll look at it later as well.

Reconsider default keybinding

See comments on #2

Potential conflict with notification package

Describe the bug
Potential conflict with notification package

To Reproduce
Steps to reproduce the behavior:

Install DocBlock-python package
display some notification, open console and run following command

var n = atom.notifications.addError('sync-settings test', {
	dismissable: true,
	buttons: [{
		text: 'Package settings',
		onDidClick () {
			atom.workspace.open('atom://config/packages/sync-settings')
			n.dismiss()
		},
	}],
})

Atom display error message in console

<embedded>:11 Uncaught TypeError: Failed to execute 'appendChild' on 'Node': parameter 1 is not of type 'Node'.
    at Object.addNotificationView (C:\Users\tokariew\AppData\Local\atom\app-1.44.0\resources\app\static\<embedded>:11:221192)
    at C:\Users\tokariew\AppData\Local\atom\app-1.44.0\resources\app\static\<embedded>:11:217303
    at Function.simpleDispatch (C:\Users\tokariew\AppData\Local\atom\app-1.44.0\resources\app\static\<embedded>:11:1212986)
    at Emitter.emit (C:\Users\tokariew\AppData\Local\atom\app-1.44.0\resources\app\static\<embedded>:11:1214427)
    at NotificationManager.addNotification (C:\Users\tokariew\AppData\Local\atom\app-1.44.0\resources\app\static\<embedded>:11:326934)
    at NotificationManager.addError (C:\Users\tokariew\AppData\Local\atom\app-1.44.0\resources\app\static\<embedded>:11:326712)
    at <anonymous>:1:28

Expected behavior

Not interfere with notification package

More info here

Add support for dataclasses

PEP 557 -- Data Classes introduced data classes (new in Python 3.7), a different way to define a class with type hinting and default parameters.

Add support for properly generating docblocks for classes using the dataclass decorator.

Support trailing commas

There is a bug in the parsing when a trailing comma is present in the definition.

E.g.:

def foo(x,):
    """Short summary.

    Parameters
    ----------
    x : type
        Description of parameter `x`.
     : type
        Description of parameter ``.

    Returns
    -------
    type
        Description of returned object.

    """
    pass

Uncaught TypeError: Cannot read property 'concat' of null

Steps to reproduce:

Create an empty class as with no attributes in the init like so:

class test():
    def __init__(self):
        pass
    pass

Run the auto doc block (i.e. ctrl+alt+d)

Atom: 1.52.0 x64
Electron: 6.1.12
OS: Microsoft Windows 10 Pro
Thrown From: docblock-python package 0.19.0

Stack Trace

Uncaught TypeError: Cannot read property 'concat' of null

At C:\Users\jon.bensing\.atom\packages\docblock-python\lib\docblock-python.js:758

TypeError: Cannot read property 'concat' of null
    at Object.process_class (/packages/docblock-python/lib/docblock-python.js:758:27)
    at /packages/docblock-python/lib/docblock-python.js:360:29
    at Array.map (<anonymous>)
    at /packages/docblock-python/lib/docblock-python.js:331:12
    at Object.generate_docblock (/packages/docblock-python/lib/docblock-python.js:395:10)
    at HTMLElement.docblockPythonGenerate_docblock (/packages/docblock-python/lib/docblock-python.js:163:53)
    at CommandRegistry.handleCommandEvent (~/AppData/Local/atom/app-1.52.0/resources/app/static/<embedded>:11:349963)
    at KeymapManager.dispatchCommandEvent (~/AppData/Local/atom/app-1.52.0/resources/app/static/<embedded>:11:1231297)
    at KeymapManager.handleKeyboardEvent (~/AppData/Local/atom/app-1.52.0/resources/app/static/<embedded>:11:1227431)
    at WindowEventHandler.handleDocumentKeyEvent (~/AppData/Local/atom/app-1.52.0/resources/app/static/<embedded>:11:284820)

Commands

  2x -0:57.8.0 core:move-up (input.hidden-input)
     -0:56.2.0 editor:newline (input.hidden-input)
     -0:54 core:backspace (input.hidden-input)
  3x -0:53.8.0 core:move-left (input.hidden-input)
  9x -0:52.4.0 core:backspace (input.hidden-input)
     -0:39.1.0 intentions:highlight (input.hidden-input)
     -0:39 core:save (input.hidden-input)
 21x -0:38.2.0 core:move-left (input.hidden-input)
  7x -0:34.5.0 core:delete (input.hidden-input)
     -0:32.8.0 intentions:highlight (input.hidden-input)
     -0:32.7.0 core:save (input.hidden-input)
  5x -0:32 core:move-down (input.hidden-input)
     -0:26.7.0 intentions:highlight (input.hidden-input)
     -0:26.6.0 core:save (input.hidden-input)
     -0:20.4.0 intentions:highlight (input.hidden-input)
     -0:20.1.0 docblock-python:generate_docblock (input.hidden-input)

Non-Core Packages

atom-ide-debugger-python 0.7.3 
atom-python-run 0.9.7 
busy-signal 2.0.1 
docblock-python 0.19.0 
ide-python 1.5.0 
intentions 1.1.5 
linter 3.1.0 
linter-ui-default 2.1.2 
minimap 4.29.9 
python-autopep8 0.1.3 
python-debugger 0.2.0 
python-terminal 0.2.0 
python-tools 0.6.9 
todo-show 2.3.2

Now I know the use case of not having any attributes should be slim to none in a class's init, but I'd thought I'd report anyways.

The work around is simply adding in an attribute or removing the init.

ignore the keyword-only argument separator

As of PEP 3102 landing in python 3, , *, can separate normally-handled arguments from keyword-only arguments. While neither the google nor numpy styleguide covers how to document keyword-only arguments, docblock-python's current behavior is to treat them like an argument to be documented. At very least, the separator shouldn't have a suggested type and description.

Current behavior

def foo(*, **kwargs):
    """Short summary.

    Args:
        * (type): Description of parameter `*`.
        **kwargs (type): Description of parameter `**kwargs`.

    Returns:
        type: Description of returned object.

    """
    pass

Desired behavior

def foo(*, **kwargs):
    """Short summary.

    Args:
        **kwargs (type): Description of parameter `**kwargs`.

    Returns:
        type: Description of returned object.

    """
    pass

References

language spec including keyword-only separator

Decouple code parsing, docstring formatting, and configuration fetching

the problem

Currently, docblock-python does all the heavy lifting: given a cursor position, it parses the class/function declaration around it, gets the docstring style configuration, and turns all of that into a well-formatted docstring. Parsing the code in particular is prone to errors (example below) and duplicates work already done by other python tools.

the benefits of decoupling

Decoupling the parsing, formatting, and configuration-getting abilities of the module would make it easier to integrate with code parsing services in the future. Writing more functional code would also make writing unit tests easier, and might even allow code reuse in other projects (I'd love to be able to import {googleStyleDocstring, getFunctionSignature} from 'docblock-python').

I've taken a first stab at making the codebase more functional in #21 .

Examples of code parsing services

The language-python and MagicPython grammars highlight function and class signatures by marking the atom HTML with scopes like .meta.function.parameters.python, .variable.parameter.function.python.

the python language server provided by ide-python could be queried via a [textDocument/signatureHelp request](https://microsoft.github.io/language-server-protocol/specification#signature-help-request-leftwards_arrow_with_hook). Example:

{
  "signatures": [
    {
      "label": "foo(a: str=1) ->int",
      "documentation": "",
      "parameters": [
        {
          "label": "a",
          "documentation": null
        }
      ]
    }
  ],
  "activeSignature": 0,
  "activeParameter": 0
}

Example python parsing bug

Example of the kind of parsing error parsing code is liable to:

async       def      foo(): return 1

won't be recognized since it doesn't have the exact string `async def` in it.

def bar(a: Complex[[TypeHint], int] = someOtherFunctionAsADefault(...)[::-1], ) -> int: ...

spadarian / docblock-python Goto Github PK

docblock-python's People

Contributors

Stargazers

Watchers

Forkers

docblock-python's Issues

Stack Trace

Commands

Non-Core Packages

Stack Trace

Commands

Non-Core Packages

Stack Trace

Commands

Non-Core Packages

Stack Trace

Commands

Non-Core Packages

Example

Stack Trace

Commands

Non-Core Packages

the problem

the benefits of decoupling

Recommend Projects

Recommend Topics

Recommend Org