pytkdocs

加载Python对象文档。

安装

使用 pip

pip install pytkdocs

使用 pipx

python3.8 -m pip install --user pipx
pipx install pytkdocs

使用 conda

conda install -c conda-forge pytkdocs

使用方法

pytkdocs 接受标准输入的JSON并写入标准输出的JSON。

输入格式

{
  "objects": [
    {
      "path": "pytkdocs",
      "new_path_syntax": false,
      "members": true,
      "inherited_members": false,
      "filters": [
        "!^_[^_]"
      ],
      "docstring_style": "google",
      "docstring_options": {
        "replace_admonitions": true
      }
    }
  ]
}

输出格式

{
  "loading_errors": [
    "string (message)"
  ],
  "parsing_errors": {
    "string (object)": [
      "string (message)"
    ]
  },
  "objects": [
    {
      "name": "pytkdocs",
      "path": "pytkdocs",
      "category": "module",
      "file_path": "/media/data/dev/pawamoy/pytkdocs/src/pytkdocs/__init__.py",
      "relative_file_path": "pytkdocs/__init__.py",
      "properties": [
        "special"
      ],
      "parent_path": "pytkdocs",
      "has_contents": true,
      "docstring": "pytkdocs package.\n\nLoad Python objects documentation.",
      "docstring_sections": [
        {
          "type": "markdown",
          "value": "pytkdocs package.\n\nLoad Python objects documentation."
        }
      ],
      "source": {
        "code": "\"\"\"\npytkdocs package.\n\nLoad Python objects documentation.\n\"\"\"\n\nfrom typing import List\n\n__all__: List[str] = []\n",
        "line_start": 1
      },
      "children": {
        "pytkdocs.__all__": {
          "name": "__all__",
          "path": "pytkdocs.__all__",
          "category": "attribute",
          "file_path": "/media/data/dev/pawamoy/pytkdocs/src/pytkdocs/__init__.py",
          "relative_file_path": "pytkdocs/__init__.py",
          "properties": [
            "special"
          ],
          "parent_path": "pytkdocs",
          "has_contents": false,
          "docstring": null,
          "docstring_sections": [],
          "source": {},
          "children": {},
          "attributes": [],
          "methods": [],
          "functions": [],
          "modules": [],
          "classes": []
        }
      },
      "attributes": [
        "pytkdocs.__all__"
      ],
      "methods": [],
      "functions": [],
      "modules": [
        "pytkdocs.__main__",
        "pytkdocs.cli",
        "pytkdocs.loader",
        "pytkdocs.objects",
        "pytkdocs.parsers",
        "pytkdocs.properties",
        "pytkdocs.serializer"
      ],
      "classes": []
    }
  ]
}

命令行

不带参数运行 pytkdocs 将读取整个标准输入，并一次性输出结果。

运行 pytkdocs --line-by-line 将进入一个无限循环，在每次迭代中，从标准输入读取一行，并将结果写回一行。这种模式实际上是为了 mkdocstrings 实现的。

配置

可用的配置选项包括

• new_path_syntax：当设置为true时，此选项强制使用新的对象路径语法，该语法使用冒号 (:) 来分隔模块和其他对象。

• filters：过滤器是正则表达式，可以根据对象的名称选择或取消选择对象。它们是递归应用的（应用于每个对象的每个子对象）。如果表达式以感叹号开头，则将过滤掉匹配的对象（感叹号在评估之前被删除）。如果不以感叹号开头，则选择匹配的对象。每个正则表达式都会针对每个名称执行。它允许细粒度过滤。示例

  • !^_：过滤掉名称以 _ 开头的每个对象（私有/受保护的）
  • ^__：但仍然选择以两个 _ 开头的对象（类私有）
  • !^__.*__$：除了那些也以两个 _ 结尾的对象（特殊对象）

• members：此选项允许显式选择顶级对象的成员。如果 True，则选择所有通过过滤器的成员。如果 False，则不选择任何内容。如果它是一个名称列表，则仅选择这些成员，并且只对其子对象应用过滤器。

• inherited_members：布尔值（默认值）。启用时，将选择继承的成员。

• docstring_style：解析文档字符串时要使用的文档字符串样式。google、restructured-text¹ 和 numpy²。

• docstring_options：传递给文档字符串解析器的选项。

  • replace_admonitions 布尔选项（默认：true）。启用时，此选项将替换缩进块的标题为它们的 Markdown 指示等价项：AdmonitionType: Title 将成为 !!! admonitiontype "Title"。
  • trim_doctest_flags 布尔选项（默认：true）。启用时，将删除位于 Python 示例块内的所有 doctest 标志（形式为 # doctest: +FLAG 和 <BLANKLINE>）从解析的输出中。

  google 文档字符串样式接受这两个选项。numpy 样式仅接受 trim_doctest_flags。restructured-text 样式不接受任何选项。

¹：reStructured Text 解析仍在积极开发中，并且尚未完全具备所有功能。
²：以下部分目前不支持：Notes、See Also、Warns 和 References。

new_path_syntax 的详细信息

示例

• 如果对象的路径中有冒号，则 pytkdocs 会根据路径值相应地分割路径，无论 new_path_syntax 的值如何。
• 如果没有冒号，并且 new_path_syntax 为 false，则 pytkdocs 使用旧的导入行为。
• 如果没有冒号，并且 new_path_syntax 为 true，则 pytkdocs 使用新的导入行为，因此认为路径指向一个模块。