键入提示并获取文档信息

Question

我有一些方法需要两个参数，它们的类型都被提示为“str”。但我也想附上一些描述。但我发现的大多数示例也希望您在文档字符串中包含类型。有没有一些巧妙的方法可以让我将类型提示保留在 docstring 之外但保留描述？

def extract_files(
        source_dir: str,
        working_dir: str,
) -> None:
    """
    Args:
        source_dir (str): some_important_description_1
        working_dir (str): some_import_description_2
    """

Answer 1

您可以在文档中拥有任何您想要的东西。如果你不想，你不必遵循特定的格式。如果您以后想要这样做，您甚至仍然可以拥有自动文档。

例如，只要文档字符串是正确的 RST，Sphinx 就会生成正确的文档。因此，您可以包含或排除任何您想要的内容。

查看更多信息： https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

我们以这段代码为例：

def extract_files(
        source_dir: str,
        working_dir: str,
) -> None:
    """
    Args:
      * ``source_dir``: some_important_description_1
      * ``working_dir``: some_import_description_2
    """
    pass

然后用autofunction创建sample.rst生成文档。

.. autofunction:: extract_files

即使文档字符串中没有类型提示，它也会生成一个看起来还不错的文档。