VS Code 使用 autoDocstring 插件快速生成 python 函数的文档字符串

支持的文档类型

• google
• sphinx
• numpy
• docBlockr
• one-line-sphinx
• pep257

用法

光标必须位于定义正下方的行上，以生成完全自动填充的文档字符串

输入三引号后按回车键（可配置"""或'''）
快捷键： ctrl+shift+2。可以在Preferences -> Keyboard Shortcuts -> extension.generateDocstring中更改。
或者右键菜单： Generate Docstring

google:（默认）

numpy:

sphinx：

扩展设置

此扩展提供以下设置：

• autoDocstring.docstringFormat：设置不同的文档类型
• autoDocstring.customTemplatePath：自定义文档字符串模板的路径（绝对或相对于项目根目录）
• autoDocstring.generateDocstringOnEnter：输入文档字符串("""或''')后按回车键生成文档字符串
• autoDocstring.includeExtendedSummary：在文档字符串中包含扩展摘要部分
• autoDocstring.includeName：在文档字符串的开头包含函数名称
• autoDocstring.startOnNewLine：摘要从新的一行开始
• autoDocstring.guessTypes：根据类型提示、默认值和变量名称推断类型
• autoDocstring.quoteStyle：文档字符串的引号样式

设置方式

ctrl+shift+p，在搜索框输入settings，选择Open Settings（UI）进行设置

接着输入docstring

自定义文档字符串模板

支持自定义模板。该扩展使用 mustache.js 模板引擎。要使用自定义模板，请创建一个.mustache文件，并使用customTemplatePath配置指定其路径。查看随附的谷歌文档字符串模板以获取使用示例。以下标记可在自定义模板中使用。

• 变量

{{name}}                        - name of the function
{{summaryPlaceholder}}          - _summary_ placeholder
{{extendedSummaryPlaceholder}}  - [extended_summary] placeholder

• 段落

{{#args}}                       - iterate over function arguments
    {{var}}                     - variable name
    {{typePlaceholder}}         - _type_ or guessed type  placeholder
    {{descriptionPlaceholder}}  - _description_ placeholder
{{/args}}

{{#kwargs}}                     - iterate over function kwargs
    {{var}}                     - variable name
    {{typePlaceholder}}         - _type_ or guessed type placeholder
    {{&default}}                - default value (& unescapes the variable)
    {{descriptionPlaceholder}}  - _description_ placeholder
{{/kwargs}}

{{#exceptions}}                 - iterate over exceptions
    {{type}}                    - exception type
    {{descriptionPlaceholder}}  - _description_ placeholder
{{/exceptions}}

{{#yields}}                     - iterate over yields
    {{typePlaceholder}}         - _type_ placeholder
    {{descriptionPlaceholder}}  - _description_ placeholder
{{/yields}}

{{#returns}}                    - iterate over returns
    {{typePlaceholder}}         - _type_ placeholder
    {{descriptionPlaceholder}}  - _description_ placeholder
{{/returns}}

附加部分

{{#argsExist}}          - display contents if args exist
{{/argsExist}}

{{#kwargsExist}}        - display contents if kwargs exist
{{/kwargsExist}}

{{#parametersExist}}    - display contents if args or kwargs exist
{{/parametersExist}}

{{#exceptionsExist}}    - display contents if exceptions exist
{{/exceptionsExist}}

{{#yieldsExist}}        - display contents if returns exist
{{/yieldsExist}}

{{#returnsExist}}       - display contents if returns exist
{{/returnsExist}}

{{#placeholder}}        - makes contents a placeholder
{{/placeholder}}