如何在Sphinx文档中自动添加参数类型 [英] How to automatically add parameter types in sphinx documentation

问题描述

我目前正在尝试使用Sphinx实现自动文档创建(使用扩展名sphinx-apidoc和napoleon).这样效果很好，但是如果将typehints(PEP484约定)自动添加到params列表中，那就更好了.

I am currently trying to implement automatic documentation creation with Sphinx (using the extensions sphinx-apidoc and napoleon). This works quite well, but it would be even better if the typehints (PEP484 convention) are added automatically to the params list.

我想知道这是否可能.

更具体地说:(摘自拿破仑示例 )

More concretely: (from the napoleon example)

def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
    """Example function with PEP 484 type annotations.

    Args:
        param1: The first parameter.
        param2: The second parameter.

    Returns:
        The return value. True for success, False otherwise.

    """

呈现如下:

参数列表具有所有参数，但不附加类型.可以手动添加它们，但是当决定更改签名时，这可能会带来将来的问题.

The parameters list has all the parameters, but does not attach the types. It is possible to add them manually, but this might introduce future problems when is decided to change the signature.

带有手动类型添加的示例:

Example with manual type addition:

def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
    """Example function with PEP 484 type annotations.

    Args:
        param1 (int): The first parameter.
        param2 (str): The second parameter.

    Returns:
        The return value. True for success, False otherwise.

    """

呈现为:

推荐答案

您现在可以使用 sphinx-autodoc-typehints 扩展名.在上面的上一个示例中编写时，它将自动将类型添加到sphinx文档字符串中.

You can now use the sphinx-autodoc-typehints extension. It will automatically add the types to the sphinx docstrings when you write in the former example above.

要安装，只需执行以下操作:

To install, just do:

$ pip install sphinx-autodoc-typehints

将'sphinx_autodoc_typehints'添加到conf.py 之后的extensions列表中，然后 'sphinx.ext.napoleon'，并确保还将napoleon_use_param = True添加到conf.py.

Add 'sphinx_autodoc_typehints' to the extensions list in conf.py after 'sphinx.ext.napoleon', and make sure you also add napoleon_use_param = True to conf.py.

这篇关于如何在Sphinx文档中自动添加参数类型的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！