Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added class and module docstrings #174

Open
wants to merge 28 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
3f07a57
added functionality for module docstring
tracetidwell Apr 26, 2020
a8f0ef3
adding regex expressions for classes & methods
bn185068 Apr 26, 2020
6ad28ab
Reversing regex
bn185068 Apr 26, 2020
07cb44e
removing a global flag
bn185068 Apr 26, 2020
125110b
added src/parse/get_class_name to fix regex issue for classes
tracetidwell Apr 26, 2020
11a2efa
Merge branch 'feature/module_docstring' of github.com:bnonni/autoDocs…
tracetidwell Apr 26, 2020
180141e
added src/parse/get_class_name to fix regex issue with classes
tracetidwell Apr 26, 2020
739b166
functionality for module and class docstrings. looks good, needs testing
tracetidwell Apr 28, 2020
cff0855
pushing fixes to broken tests
bn185068 Apr 28, 2020
d099316
parseAttributes: new regex pattern; parseClasses: different regex pat…
bn185068 Apr 28, 2020
209f1ed
getFunctionName: adding diff regex for both class and method
bn185068 Apr 28, 2020
30537c3
pulled most recent master; working on tests
tracetidwell Jan 28, 2021
0d7603e
mergingin everything into new branch
tracetidwell Jan 28, 2021
e620d1f
passing unit tests; failing integration tests
tracetidwell Jan 29, 2021
0b08830
all unit tests and integration tests passing!
tracetidwell Jan 29, 2021
1ba0736
Merge pull request #1 from bnonni/feature/module_docstring
tracetidwell Jan 29, 2021
29442b7
updated changelog; cleaning up code
tracetidwell Jan 29, 2021
1b2c384
Merge pull request #2 from bnonni/feature/module_docstring
tracetidwell Jan 29, 2021
c8ad667
refactoring for code climate compliance
tracetidwell Jan 29, 2021
b178d92
Merge pull request #3 from bnonni/feature/module_docstring
tracetidwell Jan 29, 2021
187d850
refactoring
tracetidwell Jan 29, 2021
1f7f3ef
Merge pull request #4 from bnonni/feature/module_docstring
tracetidwell Jan 29, 2021
b6eb8a4
still simplifying get_definition
tracetidwell Jan 29, 2021
24de229
Merge pull request #5 from bnonni/feature/module_docstring
tracetidwell Jan 29, 2021
63e67d1
refatoring...
tracetidwell Jan 29, 2021
0dac472
Merge pull request #6 from bnonni/feature/module_docstring
tracetidwell Jan 29, 2021
5b43992
one more try
tracetidwell Jan 29, 2021
973fb88
Merge pull request #7 from bnonni/feature/module_docstring
tracetidwell Jan 29, 2021
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .vscode/launch.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
]
}
}
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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)
Expand Down
11 changes: 10 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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}}
```
Expand Down
33 changes: 33 additions & 0 deletions module_docstring.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Changes made to autoDocstring to incorporate module level docstrings
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for this pr guide! Can you move it to a comment on the pr so that we can take it out if the code but ˆcan still read it?

- 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.
16 changes: 16 additions & 0 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 4 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -71,12 +71,13 @@
"properties": {
"autoDocstring.docstringFormat": {
"type": "string",
"default": "google",
"default": "ncr",
tracetidwell marked this conversation as resolved.
Show resolved Hide resolved
"enum": [
"docblockr",
"google",
"sphinx",
"numpy"
"numpy",
"ncr"
],
"description": "Which docstring format to use."
},
Expand Down Expand Up @@ -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",
Expand Down
2 changes: 2 additions & 0 deletions src/docstring/docstring_factory.ts
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ export class DocstringFactory {
this.includeDescription = includeDescription;

this.template = template;
// console.log('template')
tracetidwell marked this conversation as resolved.
Show resolved Hide resolved
// console.log(this.template)
}

public generateDocstring(docstringParts: DocstringParts, indentation = ""): string {
Expand Down
27 changes: 27 additions & 0 deletions src/docstring/template_data.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,11 @@ import {
KeywordArgument,
Returns,
Yields,
Method,
Attribute
} from "../docstring_parts";


export class TemplateData {
public name: string;
public decorators: Decorator[];
Expand All @@ -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;
Expand All @@ -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;
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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;
}
}
}
}
75 changes: 75 additions & 0 deletions src/docstring/templates/ncr.mustache
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
{{! NCR Docstring Template }}
tracetidwell marked this conversation as resolved.
Show resolved Hide resolved
{{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}}
16 changes: 16 additions & 0 deletions src/docstring/templates/sphinx.mustache
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,22 @@

{{extendedSummaryPlaceholder}}

{{#classesExist}}
tracetidwell marked this conversation as resolved.
Show resolved Hide resolved
Classes
-------
{{#classes}}
{{name}}
{{/classes}}
{{/classesExist}}

{{#methodsExist}}
Methods
-------
{{#methods}}
{{name}}
{{/methods}}
{{/methodsExist}}

{{#args}}
:param {{var}}: {{descriptionPlaceholder}}
:type {{var}}: {{typePlaceholder}}
Expand Down
16 changes: 16 additions & 0 deletions src/docstring_parts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@ export interface DocstringParts {
exceptions: Exception[];
returns: Returns;
yields: Yields;
classes: Method[];
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you create a separate type for classes

methods: Method[];
attributes: Attribute[];
}

export interface Decorator {
Expand Down Expand Up @@ -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;
}
tracetidwell marked this conversation as resolved.
Show resolved Hide resolved
29 changes: 24 additions & 5 deletions src/parse/get_body.ts
Original file line number Diff line number Diff line change
@@ -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);

tracetidwell marked this conversation as resolved.
Show resolved Hide resolved
}

function populateBody(currentLineNum: number, lines: string[], originalIndentation: number) {

tracetidwell marked this conversation as resolved.
Show resolved Hide resolved
const body = [];
while (currentLineNum < lines.length) {
const line = lines[currentLineNum];

Expand All @@ -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];
Expand Down
18 changes: 18 additions & 0 deletions src/parse/get_class_name.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
export function getClassName(functionDefinition: string): string {
//const pattern1 = /(?:class)\s+(\w+)\s*\(/;
const pattern1 = /(?:class)\s+(\w+)/;
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These patterns look the same.

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 "";
}
}
Loading