类型提示和文档信息

Question

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

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

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

类型提示和文档信息

Type hinting and having docs information

python

types

docstring