Added class and module docstrings

.vscode/launch.json

@@ -20,12 +20,12 @@
 			"runtimeExecutable": "${execPath}",
 			"args": [
 				"--extensionDevelopmentPath=${workspaceFolder}",
-				"--extensionTestsPath=${workspaceFolder}/out/test"
+				"--extensionTestsPath=${workspaceFolder}/src/test/integration/index.ts"
 			],
 			"outFiles": [
 				"${workspaceFolder}/out/test/**/*.js"
 			],
 			"preLaunchTask": "npm: compile"
 		}
 	]
-}
+}

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Change Log
 
+## [0.5.5] - 2021-01-17
+
+-   Added class and module docstrings (@tracetidwell)
+
 ## [0.5.4] - 2020-11-17
 
 -   Added Starlark support #139 (@UebelAndre)

README.md

@@ -25,7 +25,7 @@ Visual Studio Code extension to quickly generate docstrings for python functions
 
 ## Usage
 
-Cursor must be on the line directly below the definition to generate full auto-populated docstring
+Cursor must be on the line directly below the class or method definition or on the first line of the file to generate full auto-populated docstring
 
 -   Press enter after opening docstring with triple quotes (`"""` or `'''`)
 -   Keyboard shortcut: `ctrl+shift+2` or `cmd+shift+2` for mac
@@ -111,6 +111,15 @@ This extension now supports custom templates. The extension uses the [mustache.j
 {{#returnsExist}}       - display contents if returns exist
 {{/returnsExist}}
 
+{{#classesExist}}       - display contents if classes exist
+{{/classesExist}}
+
+{{#methodsExist}}       - display contents if methods exist
+{{/methodsExist}}
+
+{{#attributesExist}}    - display contents if attributes exist
+{{/attributesExist}}
+
 {{#placeholder}}        - makes contents a placeholder
 {{/placeholder}}
 ```

module_docstring.md

@@ -0,0 +1,33 @@
+# Changes made to autoDocstring to incorporate module level docstrings
+- src/parse/get_body.ts
+    - getBody(): if docstring is being added at first line of document, return entire document as body
+- src/docstring_parts.ts
+    - DocstringParts: added Class[] and Method[] attributes
+    - Class: Created Class interface
+    - Method: Created Method interface
+- src/parse/parse_parameters.ts
+    - parseParameters(): added positionLine argument, if positionLine == 0 return only top-level classes and methods, otherwise return normal DocstringParts
+    - parseClasses(): returns list of top-level classes
+    - parseMethods(): returns list of top-level methods
+- src/docstring/template_data.ts
+    - TemplateData: added classes and methods attributes, updated constructor to take list of classes and list of methods
+        - classesExist(): added method to check if classes exist, needed to parse template
+        - methodsExist(): added method to check if methods exist, needed to parse template
+- src/docstring/templates/ncr.mustache
+    - Created template file that incorporates classes and methods
+- package.json
+    - contributes.configuration.properties.autoDocstring.docstringFormat.enum
+        - Added "ncr" template (this should probably be removed)
+    - contributes.commands[0].title
+        - Changed to "Generate Docstring2" just to avoid any confusion, will change back when ready for PR
+
+# To run the code
+- Open the autoDocstring folder in VS Code
+- Open the command palette (Ctrl+Shift+P) and type `settings.json` to open the settings configuration file
+- Add the line `"autoDocstring.customTemplatePath": "/home/shared/Projects/autoDocstring/src/docstring/templates/ncr.mustache"` and make sure the path to the ncr.mustache template is correct for your computer.
+- Save and close settings.json.
+- Press F5
+- Click "Debug Anyway"
+- When the new screen opens, open a folder to any project you want to add a module level docstring to
+- On line 1, click Ctrl+Shift+P or input """ and press enter.
+- The docstring should populate and list all top-level classes and methods in the file.

package.json

@@ -71,12 +71,13 @@
             "properties": {
                 "autoDocstring.docstringFormat": {
                     "type": "string",
-                    "default": "google",
+                    "default": "ncr",
                     "enum": [
                         "docblockr",
                         "google",
                         "sphinx",
-                        "numpy"
+                        "numpy",
+                        "ncr"
                     ],
                     "description": "Which docstring format to use."
                 },
@@ -145,6 +146,7 @@
     },
     "devDependencies": {
         "@types/chai": "^4.2.11",
+        "@types/glob": "^7.1.3",
         "@types/mocha": "^5.2.7",
         "@types/mustache": "^0.8.32",
         "@types/node": "^13.13.1",

src/docstring/docstring_factory.ts

@@ -27,6 +27,8 @@ export class DocstringFactory {
         this.includeDescription = includeDescription;
 
         this.template = template;
+        // console.log('template')
+        // console.log(this.template)
     }
 
     public generateDocstring(docstringParts: DocstringParts, indentation = ""): string {

src/docstring/template_data.ts

@@ -6,8 +6,11 @@ import {
     KeywordArgument,
     Returns,
     Yields,
+    Method,
+    Attribute
 } from "../docstring_parts";
 
+
 export class TemplateData {
     public name: string;
     public decorators: Decorator[];
@@ -16,6 +19,9 @@ export class TemplateData {
     public exceptions: Exception[];
     public returns: Returns;
     public yields: Yields;
+    public classes: Method[];
+    public methods: Method[];
+    public attributes: Attribute[];
 
     private includeName: boolean;
     private includeExtendedSummary: boolean;
@@ -33,6 +39,9 @@ export class TemplateData {
         this.exceptions = docstringParts.exceptions;
         this.returns = docstringParts.returns;
         this.yields = docstringParts.yields;
+        this.classes = docstringParts.classes;
+        this.methods = docstringParts.methods;
+        this.attributes = docstringParts.attributes;
 
         this.includeName = includeName;
         this.includeExtendedSummary = includeExtendedSummary;
@@ -99,6 +108,18 @@ export class TemplateData {
         return this.yields != undefined;
     }
 
+    public classesExist(): boolean {
+        return this.classes.length > 0;
+    }
+
+    public methodsExist(): boolean {
+        return this.methods.length > 0;
+    }
+
+    public attributesExist(): boolean {
+        return this.attributes.length > 0;
+    }
+
     private removeTypes(): void {
         for (const arg of this.args) {
             arg.type = undefined;
@@ -139,5 +160,11 @@ export class TemplateData {
         if (yields != undefined && yields.type == undefined) {
             yields.type = placeholder;
         }
+
+        for (const attribute of this.attributes) {
+            if (attribute.type === undefined) {
+                attribute.type = placeholder;
+            }
+        }
     }
 }

src/docstring/templates/ncr.mustache

@@ -0,0 +1,75 @@
+{{! NCR Docstring Template }}
+{{summaryPlaceholder}}
+
+{{extendedSummaryPlaceholder}}
+
+{{#classesExist}}
+Classes
+-------
+{{#classes}}
+{{name}}
+{{/classes}}
+{{/classesExist}}
+
+{{#methodsExist}}
+Methods
+-------
+{{#methods}}
+{{name}}
+{{/methods}}
+{{/methodsExist}}
+
+{{#parametersExist}}
+Parameters
+----------
+{{#args}}
+{{var}} : {{typePlaceholder}}
+    {{descriptionPlaceholder}}
+
+{{/args}}
+{{#kwargs}}
+{{var}} : {{typePlaceholder}}, optional
+    {{descriptionPlaceholder}}, by default {{&default}}
+
+{{/kwargs}}
+{{/parametersExist}}
+
+{{#attributesExist}}
+Attributes
+----------
+{{#attributes}}
+{{var}} : {{typePlaceholder}}
+    {{descriptionPlaceholder}}
+
+{{/attributes}}
+{{/attributesExist}}
+
+{{#returnsExist}}
+Returns
+-------
+{{#returns}}
+return_val : {{typePlaceholder}}
+    {{descriptionPlaceholder}}
+
+{{/returns}}
+{{/returnsExist}}
+
+{{#yieldsExist}}
+Yields
+-------
+{{#yields}}
+yield_val : {{typePlaceholder}}
+    {{descriptionPlaceholder}}
+
+{{/yields}}
+{{/yieldsExist}}
+
+{{#exceptionsExist}}
+Raises
+------
+{{#exceptions}}
+{{type}}
+    {{descriptionPlaceholder}}
+
+{{/exceptions}}
+{{/exceptionsExist}}

src/docstring/templates/sphinx.mustache

@@ -3,6 +3,22 @@
 
 {{extendedSummaryPlaceholder}}
 
+{{#classesExist}}
+Classes
+-------
+{{#classes}}
+{{name}}
+{{/classes}}
+{{/classesExist}}
+
+{{#methodsExist}}
+Methods
+-------
+{{#methods}}
+{{name}}
+{{/methods}}
+{{/methodsExist}}
+
 {{#args}}
 :param {{var}}: {{descriptionPlaceholder}}
 :type {{var}}: {{typePlaceholder}}

src/docstring_parts.ts

@@ -6,6 +6,9 @@ export interface DocstringParts {
     exceptions: Exception[];
     returns: Returns;
     yields: Yields;
+    classes: Method[];
+    methods: Method[];
+    attributes: Attribute[];
 }
 
 export interface Decorator {
@@ -34,3 +37,16 @@ export interface Returns {
 export interface Yields {
     type: string;
 }
+
+// export interface Class {
+//     name: string;
+// }
+
+export interface Method {
+    name: string;
+}
+
+export interface Attribute {
+    var: string;
+    type: string;
+}

src/parse/get_body.ts

@@ -1,12 +1,30 @@
 import { blankLine, indentationOf, preprocessLines } from "./utilities";
 
-export function getBody(document: string, linePosition: number): string[] {
+export function getBody(docstringType: string, document: string, linePosition: number): string[] {
     const lines = document.split("\n");
-    const body = [];
+    let regex = '\s*def \w+'
+
+    if (docstringType === 'module') {
+        return lines;
+    }
+    else if (docstringType === 'class') {
+        regex = '.';
+    }
 
     let currentLineNum = linePosition;
-    const originalIndentation = getBodyBaseIndentation(lines, linePosition);
+    const originalIndentation = getBodyBaseIndentation(lines, linePosition, regex);
+
+    if (originalIndentation === 0) {
+        return [];
+    }
 
+    return populateBody(currentLineNum, lines, originalIndentation);
+
+}
+
+function populateBody(currentLineNum: number, lines: string[], originalIndentation: number) {
+
+    const body = [];
     while (currentLineNum < lines.length) {
         const line = lines[currentLineNum];
 
@@ -26,9 +44,10 @@ export function getBody(document: string, linePosition: number): string[] {
     return preprocessLines(body);
 }
 
-function getBodyBaseIndentation(lines: string[], linePosition: number): number {
+function getBodyBaseIndentation(lines: string[], linePosition: number, regex: string): number {
     let currentLineNum = linePosition;
-    const functionDefRegex = /\s*def \w+/;
+    //const functionDefRegex = /\s*def \w+/;
+    const functionDefRegex = RegExp(regex)
 
     while (currentLineNum < lines.length) {
         const line = lines[currentLineNum];

src/parse/get_class_name.ts

@@ -0,0 +1,18 @@
+export function getClassName(functionDefinition: string): string {
+    //const pattern1 = /(?:class)\s+(\w+)\s*\(/;
+    const pattern1 = /(?:class)\s+(\w+)/;
+    const pattern2 = /(?:class)\s+(\w+)/;
+
+    const match1 = pattern1.exec(functionDefinition);
+    const match2 = pattern2.exec(functionDefinition);
+
+    if (match1 != undefined && match1[1] != undefined) {
+        return match1[1];
+    }
+    else if (match2 != undefined && match2[1] != undefined) {
+        return match2[1]
+    }
+    else {
+        return "";
+    }
+}