sphinx-apidoc无法理解var并在一行中键入args。怎么解决这个问题？

Question

我使用sphinx reSt为函数编写文档字符串，并创建了一个胡子设置，用于自定义VsCode中的docstring自动生成，如下所示：

{{! Sphinx Docstring Template }}
{{summaryPlaceholder}}

{{extendedSummaryPlaceholder}}

{{#args}}
:param {{var}} {{typePlaceholder}}: {{descriptionPlaceholder}}
{{/args}}
{{#kwargs}}
:param {{var}} {{typePlaceholder}}{{#default}}, optional defaults to {{/default}}{{&default}}: {{descriptionPlaceholder}}
{{/kwargs}}
{{#exceptionsExist}}

{{#exceptions}}
:raises {{type}}: {{descriptionPlaceholder}}
{{/exceptions}}
{{/exceptionsExist}}
{{#yieldsExist}}

{{#yields}}
:yield {{typePlaceholder}}: {{descriptionPlaceholder}}
{{/yields}}
{{/yieldsExist}}
{{#returnsExist}}

{{#returns}}
:return {{typePlaceholder}}: {{descriptionPlaceholder}}
{{/returns}}
{{/returnsExist}}

例如：

# myproject/src/foo.py

def my_func(arg1: int, arg2: int, arg3: str = "some_text") -> tuple[str, str, str]:
    """my summary
     
    my extended_summary
     
    :param arg1 int: arg1 my description
    :param arg2 int: arg2 my description
    :param arg3 str Default "some_text": arg3 my description
     
    :return tuple[str, str, str]: return my description
    """
 
    return "a", "b", "c"

现在我将使用sphinx-apidoc 来生成文档

我在sphinx-quickstart做myproject/docs。然后运行sphinx-apidoc -o ./docs/_modules ./src，然后将目录更改为docs并运行make html

但是，为我生成的文档如下：

​

​

如果我将函数的docstring修改为标准格式，如下所示：

def my_func(arg1: int, arg2: int, arg3: str = "some_text") -> tuple[str, str, str]:
    """my summary
     
    my extended_summary

    :param arg1: arg1 my description
    :type arg1: int
    :param arg2: arg2 my description
    :type arg2: int
    :param arg3: arg3 my description, defaults to "some_text"
    :type arg3: str, optional
    :return: return my description
    :rtype: tuple[str, str, str]
    """

    return "a", "b", "c"

生成正确的文档。

​

​

由于我为docstring创建的模板是一个标准的替代方案，如何调整sphinx以使用我的胡子模板并生成正确的文档？

**夏季：

• ，我已经用胡子
• 定制了自动文档扩展，我需要sphinx-apidoc来正确地理解生成的文档字符串**

。

Answer 1

我认为@mzn的评论才是这个问题的真正答案。

顺便说一句，自定义sphinx输出的通常方法是使用Jinja模板。见

总之，我修改了胡子文件，我得到了预期的结果：

{{! Sphinx Docstring Template }}
{{summaryPlaceholder}}

{{extendedSummaryPlaceholder}}

{{#args}}
:param {{typePlaceholder}} {{var}}: {{descriptionPlaceholder}}
{{/args}}
{{#kwargs}}
:param {{typePlaceholder}}{{#default}}, optional {{var}}: {{descriptionPlaceholder}}, defaults to {{/default}}{{&default}}
{{/kwargs}}
{{#exceptionsExist}}

{{#exceptions}}
:raises {{type}}: {{descriptionPlaceholder}}
{{/exceptions}}
{{/exceptionsExist}}
{{#yieldsExist}}

{{#yields}}
:yield {{typePlaceholder}}: {{descriptionPlaceholder}}
{{/yields}}
{{/yieldsExist}}
{{#returnsExist}}

{{#returns}}
:return: {{descriptionPlaceholder}}
:rtype: {{typePlaceholder}}
{{/returns}}
{{/returnsExist}}

def my_func(arg1: int, arg2: int, arg3: str = "some_text") -> tuple[str, str, str]:
    """summary
    
    extended_summary
    
    :param int arg1: description
    :param int arg2: description
    :param str, optional arg3: description, defaults to "some_text"
    
    :return: description
    :rtype: tuple[str, str, str]
    """
 
    return "a", "b", "c"

​

​