Merge branch 'master' into reverse-mustache

* master: (29 commits) Merge publish and test workflows Handle nested square brackets in type hints (#185) Improve changelog format and add publish release action Only run publish workflow after successful test workflow Bump version to 0.6.1 Remove one-line-sphinx-notypes and update changelog Add example documentation of docstring formats (#224) Rename oneline-rst to one-line-sphinx Bump version to 0.6.0 Fixes #212: Parse Literal type hints in function definition (#223) Add debug log statements Update all dependencies (#222) Add more notypes docstring templates (#221) Fixes #94: Switch square brackets in placeholder to underscores (#220) Avoid extra newlines in templates (#203) Add oneline-rst docstring to menu and readme so its accessible (#195) Add PEP 604 style type hint support (#218) Fix yield underline in numpy template (#216) Update READEME Switch to github actions (#214) ...
NilsJPWerner · Feb 16, 2022 · 27b2792 · 27b2792
2 parents 3885c4f + 74383d0
commit 27b2792
Show file tree

Hide file tree

Showing 62 changed files with 1,688 additions and 780 deletions.
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
@@ -0,0 +1 @@
+github: NilsJPWerner
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -1,38 +1,51 @@
 ---
 name: Bug report
 about: Create a report to help us improve
-title: ''
+title: ""
 labels: bug
-assignees: ''
-
+assignees: ""
 ---
 
 **Describe the bug**
 A clear and concise description of what the bug is.
 
 **Versions (please complete the following information):**
-- autoDocstring Version: 
-- Operating System: 
-- Vscode Version: 
+
+-   autoDocstring Version:
+-   Operating System:
+-   Vscode Version:
 
 **Original Code (with line to generate on):**
+
 ```python
 # generate on this line
 ```
 
 **Expected Result:**
+
 ```python
+
 ```
 
 **Actual Result:**
+
 ```python
+
 ```
 
-**Stack trace:**
-If an error was reported by autodocstring please copy the stack trace from the `autoDocstring` output channel.
+**Debug log:**
+Set `autoDocstring.logLevel` to "Debug", recreate the bug, and then copy the debug logs from the `autoDocstring` output channel.
+
 ```
+
 ```
 
+**Stack trace:**
+If an error was reported by autoDocstring please copy the stack trace from the `autoDocstring` output channel.
+
+```
+
+```
 
 **Additional context**
 Add any other context about the problem here.
diff --git a/.gitignore b/.gitignore
@@ -9,3 +9,4 @@ test_*
 *.psd
 todo
 scratch
+autodocstring-*.vsix
diff --git a/.travis.yml b/.travis.yml
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -1,12 +1,14 @@
 {
     "version": "0.2.0",
-	"configurations": [{
+	"configurations": [
+		{
 			"name": "Run Extension",
 			"type": "extensionHost",
 			"request": "launch",
 			"runtimeExecutable": "${execPath}",
 			"args": [
-				"--extensionDevelopmentPath=${workspaceFolder}"
+				"--extensionDevelopmentPath=${workspaceFolder}",
+				"--trace-deprecation"
 			],
 			"outFiles": [
 				"${workspaceFolder}/out/**/*.js"
@@ -20,7 +22,8 @@
 			"runtimeExecutable": "${execPath}",
 			"args": [
 				"--extensionDevelopmentPath=${workspaceFolder}",
-				"--extensionTestsPath=${workspaceFolder}/out/test"
+				"--extensionTestsPath=${workspaceFolder}/out/test",
+				"--trace-deprecation"
 			],
 			"outFiles": [
 				"${workspaceFolder}/out/test/**/*.js"

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,82 +1,143 @@
 # Change Log
 
-## [0.5.3] - 2020-06-03
+## Unreleased
+
+[All Changes](https://github.com/NilsJPWerner/autoDocstring/compare/v0.6.1...master)
+
+## [0.6.1](https://github.com/NilsJPWerner/autoDocstring/tree/v0.6.1) - 2022-02-15
+
+-   Rename oneline-rst to one-line-sphinx
+-   Remove oneline-rst-notypes as provided format
+-   Documentation: Add examples of docstrings formats ([#224](https://github.com/NilsJPWerner/autoDocstring/issues/224))
+
+[All Changes](https://github.com/NilsJPWerner/autoDocstring/compare/v0.5.4...v0.6.0)
+
+## [0.6.0](https://github.com/NilsJPWerner/autoDocstring/tree/v0.6.0) - 2022-02-13
+
+-   Added one line sphinx format support ([#169](https://github.com/NilsJPWerner/autoDocstring/issues/169)) (@sam-hoffman @afarntrog)
+-   Switched to github actions ([#214](https://github.com/NilsJPWerner/autoDocstring/issues/214)) (@s-weigand)
+-   Switched placeholder wrapper from square brackets to underscore ([#220](https://github.com/NilsJPWerner/autoDocstring/issues/220))
+-   Add untyped versions of docstring formats ([#209](https://github.com/NilsJPWerner/autoDocstring/issues/209)) (@Lef-F)
+-   Updated javascript dependencies ([#222](https://github.com/NilsJPWerner/autoDocstring/issues/222))
+-   Added more extensive debug logging
+-   Added PEP 604 type hint support for pipes ([#218](https://github.com/NilsJPWerner/autoDocstring/issues/218)) (@s-weigand)
+-   Fixed bug: Broken quoted type hint forward references ([#157](https://github.com/NilsJPWerner/autoDocstring/issues/157)) (@IniasP)
+-   Fixed bug: Extra underscore in numpy template ([#216](https://github.com/NilsJPWerner/autoDocstring/issues/216)) (@s-weigand)
+-   Fixed bug: Extra newlines between sections in some cases ([#203](https://github.com/NilsJPWerner/autoDocstring/issues/203)) (@shaperilio)
+-   Fixed bug: Incorrectly parses Literal type hints ([#223](https://github.com/NilsJPWerner/autoDocstring/issues/223))
+-   Documentation: Quotes clarification ([#211](https://github.com/NilsJPWerner/autoDocstring/issues/211)) (@johschmitz)
+
+[All Changes](https://github.com/NilsJPWerner/autoDocstring/compare/v0.5.4...v0.6.0)
+
+## [0.5.4](https://github.com/NilsJPWerner/autoDocstring/tree/v0.5.4) - 2020-11-17
+
+-   Added Starlark support ([#139](https://github.com/NilsJPWerner/autoDocstring/issues/139)) (@UebelAndre)
+-   Fixed bug: Ignore "raise" in comments ([#138](https://github.com/NilsJPWerner/autoDocstring/issues/138)) (@bastienboutonnet)
+-   Fixed bug: Discard lines that are only comments ([#146](https://github.com/NilsJPWerner/autoDocstring/issues/146)) (@HaaLeo)
+
+[All Changes](https://github.com/NilsJPWerner/autoDocstring/compare/v0.5.3...v0.5.4)
+
+## [0.5.3](https://github.com/NilsJPWerner/autoDocstring/tree/v0.5.3) - 2020-06-03
 
 -   Changed default docstring type to google
 -   Added better logging and stack traces for errors
--   Fixed bug: Comments in multiline function definition are not ignored #77
--   Fixed bug: Parse quoted type hints #138 (@bastienboutonnet)
--   Fixed bug: Parsing fails when activated on first line #139
+-   Fixed bug: Comments in multiline function definition are not ignored ([#77](https://github.com/NilsJPWerner/autoDocstring/issues/77))
+-   Fixed bug: Parse quoted type hints ([#138](https://github.com/NilsJPWerner/autoDocstring/issues/138)) (@bastienboutonnet)
+-   Fixed bug: Parsing fails when activated on first line ([#139](https://github.com/NilsJPWerner/autoDocstring/issues/139))
 -   Fixed bug: Unclear error when a document type is not supported. e.g. notebooks
 
-## [0.5.2] - 2020-05-17
+[All Changes](https://github.com/NilsJPWerner/autoDocstring/compare/v0.5.2...v0.5.3)
+
+## [0.5.2](https://github.com/NilsJPWerner/autoDocstring/tree/v0.5.2) - 2020-05-17
 
--   Fixed bug: Multiline function definitions are not parsed correctly #74
--   Fixed bug: No indentation if function is blank #117 (@rileypeterson)
--   Fixed bug: CompletionItem not appearing after triple single quote #125
+-   Fixed bug: Multiline function definitions are not parsed correctly ([#74](https://github.com/NilsJPWerner/autoDocstring/issues/74))
+-   Fixed bug: No indentation if function is blank ([#117](https://github.com/NilsJPWerner/autoDocstring/issues/117)) (@rileypeterson)
+-   Fixed bug: CompletionItem not appearing after triple single quote ([#125](https://github.com/NilsJPWerner/autoDocstring/issues/125))
 
-## [0.5.1] - 2020-04-28
+[All Changes](https://github.com/NilsJPWerner/autoDocstring/compare/v0.5.1...v0.5.2)
 
--   Fixed bug: No completion item in CRLF documents #118
+## [0.5.1](https://github.com/NilsJPWerner/autoDocstring/tree/v0.5.1) - 2020-04-28
 
-## [0.5.0] - 2020-04-21
+-   Fixed bug: No completion item in CRLF documents ([#118](https://github.com/NilsJPWerner/autoDocstring/issues/118))
+
+[All Changes](https://github.com/NilsJPWerner/autoDocstring/compare/v0.5.0...v0.5.1)
+
+## [0.5.0](https://github.com/NilsJPWerner/autoDocstring/tree/v0.5.0) - 2020-04-21
 
 -   Added remote usage capabilities
 -   Switched to completionItem API and improved activation detection
 -   Added integration tests
--   Fixed bug: Trailing whitespace on blank lines #99
+-   Fixed bug: Trailing whitespace on blank lines ([#99](https://github.com/NilsJPWerner/autoDocstring/issues/99))
 -   Fixed bug: Lines are parsed after end of function
--   Fixed bug: Wrong docstring for yield-only generator #91 (@HaaLeo)
--   Fixed bug: Comments in definition cause parsing errors #110
+-   Fixed bug: Wrong docstring for yield-only generator ([#91](https://github.com/NilsJPWerner/autoDocstring/issues/91)) (@HaaLeo)
+-   Fixed bug: Comments in definition cause parsing errors ([#110](https://github.com/NilsJPWerner/autoDocstring/issues/110))
+
+[All Changes](https://github.com/NilsJPWerner/autoDocstring/compare/v0.4.0...v0.5.0)
 
-## [0.4.0] - 2019-11-13
+## [0.4.0](https://github.com/NilsJPWerner/autoDocstring/tree/v0.4.0) - 2019-11-13
 
 -   Omit `-> None` return annotation (@HaaLeo)
 -   Add support for yields (@HaaLeo)
 -   Add support for relative paths in `customTemplatePath` configuration (@s-kovacevic)
 -   Indent correctly on `> Generate Docstring` command
 
-## [0.3.0] - 2019-04-16
+[All Changes](https://github.com/NilsJPWerner/autoDocstring/compare/v0.3.0...v0.4.0)
+
+## [0.3.0](https://github.com/NilsJPWerner/autoDocstring/tree/v0.3.0) - 2019-04-16
 
 -   Switched to mustache.js for templating
 -   Added support for custom templating
 -   Fixed bug - newline after generating docstring
 
-## [0.2.3] - 2018-07-23
+[All Changes](https://github.com/NilsJPWerner/autoDocstring/compare/v0.2.3...v0.3.0)
+
+## [0.2.3](https://github.com/NilsJPWerner/autoDocstring/tree/v0.2.3) - 2018-07-23
 
 -   Added support for single quotes (@Modelmat)
 -   Bugfixes (@chirieac, @md2perpe)
 
-## [0.2.1] - 2018-04-15
+[All Changes](https://github.com/NilsJPWerner/autoDocstring/compare/v0.2.1...v0.2.3)
+
+## [0.2.1](https://github.com/NilsJPWerner/autoDocstring/tree/v0.2.1) - 2018-04-15
 
 -   Bugfixes
 -   Added includeName option to include function name in docstring
 -   Added newlineBeforeSummary option
 -   Removed test functions from install script
 
-## [0.2.0] - 2018-02-28
+[All Changes](https://github.com/NilsJPWerner/autoDocstring/compare/v0.2.1...v0.2.3)
+
+## [0.2.0](https://github.com/NilsJPWerner/autoDocstring/tree/v0.2.0) - 2018-02-28
 
 -   Rewrote parser to tokenize parameters. Should deal with string and array kwargs better
 -   Added type inference using type hints, kwarg defaults, and var names
 -   Improved the closed docstring check
 -   Added unit tests for parser
 
-## [0.1.4] - 2018-01-17
+[All Changes](https://github.com/NilsJPWerner/autoDocstring/compare/v0.1.4...v0.2.0)
+
+## [0.1.4](https://github.com/NilsJPWerner/autoDocstring/tree/v0.1.4) - 2018-01-17
 
 -   Add Sphinx and Numpy formatters
 
-## [0.1.3] - 2018-01-01
+[All Changes](https://github.com/NilsJPWerner/autoDocstring/compare/v0.1.3...v0.1.4)
+
+## [0.1.3](https://github.com/NilsJPWerner/autoDocstring/tree/v0.1.3) - 2018-01-01
 
 -   Bugfixes
 -   Better documentation
 -   Fixed parsers
 
-## [0.1.2] - 2017-11-22
+[All Changes](https://github.com/NilsJPWerner/autoDocstring/compare/v0.1.2...v0.1.3)
+
+## [0.1.2](https://github.com/NilsJPWerner/autoDocstring/tree/v0.1.2) - 2017-11-22
 
 -   Changed name, added logo, cleaned up readme, and added explanatory gif
 -   Will get better at change logs!
 
-## [0.1.0] - 2017-11-18
+[All Changes](https://github.com/NilsJPWerner/autoDocstring/compare/v0.1.0...v0.1.2)
+
+## [0.1.0](https://github.com/NilsJPWerner/autoDocstring/tree/v0.1.0) - 2017-11-18
 
 -   Supports google and typed PEP0257 style docstrings
 -   Supports automatic creation on enter after triple quotes

diff --git a/README.md b/README.md
@@ -1,8 +1,9 @@
-[![Build Status](https://travis-ci.org/NilsJPWerner/autoDocstring.svg?branch=master)](https://travis-ci.org/NilsJPWerner/autoDocstring)
 [![Installs](https://vsmarketplacebadge.apphb.com/installs-short/njpwerner.autodocstring.svg)](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring)
 [![Rating](https://vsmarketplacebadge.apphb.com/rating-short/njpwerner.autodocstring.svg)](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring&ssr=false#review-details)
+[![Build Status](https://github.com/NilsJPWerner/autoDocstring/actions/workflows/test.yml/badge.svg)](https://github.com/NilsJPWerner/autoDocstring/actions/workflows/test.yml)
+[![Github Sponsorship](https://img.shields.io/badge/sponsor-5A5A5A?style=flat&logo=GitHub-Sponsors)](https://github.com/sponsors/NilsJPWerner)
 
-# VSCode Python Docstring Generator
+# autoDocstring: VSCode Python Docstring Generator
 
 Visual Studio Code extension to quickly generate docstrings for python functions.
 
@@ -17,17 +18,20 @@ Visual Studio Code extension to quickly generate docstrings for python functions
 
 ## Docstring Formats
 
--   Google (default)
--   docBlockr
--   Numpy
--   Sphinx
--   PEP0257 (coming soon)
+To turn off type generation in docstrings use the `-notypes` template of the desired format. The docBlockr format is a typed version of PEP0257.
+
+-   [google](docs/google.md)
+-   [sphinx](docs/sphinx.md)
+-   [numpy](docs/numpy.md)
+-   [docBlockr](docs/docblockr.md)
+-   [one-line-sphinx](docs/one-line-sphinx.md)
+-   [pep257](docs/pep257.md)
 
 ## Usage
 
 Cursor must be on the line directly below the definition to generate full auto-populated docstring
 
--   Press enter after opening docstring with triple quotes (`"""` or `'''`)
+-   Press enter after opening docstring with triple quotes (configurable `"""` or `'''`)
 -   Keyboard shortcut: `ctrl+shift+2` or `cmd+shift+2` for mac
     -   Can be changed in Preferences -> Keyboard Shortcuts -> extension.generateDocstring
 -   Command: `Generate Docstring`
@@ -54,7 +58,7 @@ This extension now supports custom templates. The extension uses the [mustache.j
 
 ```
 {{name}}                        - name of the function
-{{summaryPlaceholder}}          - [summary] placeholder
+{{summaryPlaceholder}}          - _summary_ placeholder
 {{extendedSummaryPlaceholder}}  - [extended_summary] placeholder
 ```
 
@@ -63,30 +67,30 @@ This extension now supports custom templates. The extension uses the [mustache.j
 ```
 {{#args}}                       - iterate over function arguments
     {{var}}                     - variable name
-    {{typePlaceholder}}         - [type] or guessed type  placeholder
-    {{descriptionPlaceholder}}  - [description] placeholder
+    {{typePlaceholder}}         - _type_ or guessed type  placeholder
+    {{descriptionPlaceholder}}  - _description_ placeholder
 {{/args}}
 
 {{#kwargs}}                     - iterate over function kwargs
     {{var}}                     - variable name
-    {{typePlaceholder}}         - [type] or guessed type placeholder
+    {{typePlaceholder}}         - _type_ or guessed type placeholder
     {{&default}}                - default value (& unescapes the variable)
-    {{descriptionPlaceholder}}  - [description] placeholder
+    {{descriptionPlaceholder}}  - _description_ placeholder
 {{/kwargs}}
 
 {{#exceptions}}                 - iterate over exceptions
     {{type}}                    - exception type
-    {{descriptionPlaceholder}}  - [description] placeholder
+    {{descriptionPlaceholder}}  - _description_ placeholder
 {{/exceptions}}
 
 {{#yields}}                     - iterate over yields
-    {{typePlaceholder}}         - [type] placeholder
-    {{descriptionPlaceholder}}  - [description] placeholder
+    {{typePlaceholder}}         - _type_ placeholder
+    {{descriptionPlaceholder}}  - _description_ placeholder
 {{/yields}}
 
 {{#returns}}                    - iterate over returns
-    {{typePlaceholder}}         - [type] placeholder
-    {{descriptionPlaceholder}}  - [description] placeholder
+    {{typePlaceholder}}         - _type_ placeholder
+    {{descriptionPlaceholder}}  - _description_ placeholder
 {{/returns}}
 ```
-Original file line number
+Diff line change
@@ Expand Up / @@ -9,3 +9,4 @@ test_* @@
     *.psd
     todo
     scratch
+    autodocstring-*.vsix