pdocs 1.2.0

阅读最新文档 - 浏览GitHub代码库

pdocs 是一个库和命令行程序，用于发现Python模块或包的公共接口。可以使用 pdocs 脚本生成模块公共接口的Markdown或HTML，或者使用它运行一个HTTP服务器，为已安装的模块提供生成的HTML。

pdocs 是Andrew Gallant (@BurntSushi)的原始实现pdoc的MIT许可分支，目的是保持与项目创建者设定的原始愿景一致。

注意：对于大多数项目，使用 pdocs 的最佳方式是使用 portray。

功能

• 支持通过遍历抽象语法来文档化数据表示，以找到模块、类和实例变量的docstrings。
• 对于不适用docstrings的情况（例如，如namedtuple），可以在您的模块中使用特殊变量 __pdocs__ 来文档化公共接口中的任何标识符。
• 使用很简单。只需将文档编写为Markdown。没有添加特殊语法规则。
• pdocs 尊重您的 __all__ 变量（如果存在）。
• pdocs 会自动将您的docstrings中的标识符链接到相应的文档。
• 当 pdocs 作为HTTP服务器运行时，支持包之间的外部链接。
• pdocs HTTP服务器会缓存生成的文档，并在源代码更新时自动重新生成。
• 当可用时，可以在HTML文档中查看模块、函数和类的源代码。
• 当可能时，使用继承来推断类成员的docstrings。

上述功能在pdocs的文档中有更详细的解释。

pdocs与Python 3.6及更高版本兼容。

快速入门

以下指南应能帮助您快速使用pdocs。

1. 安装 - TL;DR：在项目的虚拟环境中运行pip3 install pdocs。
2. 命令行使用 - TL;DR：运行pdocs server YOUR_MODULES进行测试，运行pdocs as_html YOUR_MODULES生成HTML。
3. API使用 - TL;DR：CLI中可用的所有内容也可以通过Python程序轻松访问。

pdocs与pdoc之间的差异

以下是pdoc和pdocs之间有意为之的差异列表

• pdocs支持内置的Markdown文档生成（如portray所需）。
• pdocs支持在参考文档中包含类型注释信息。
• pdocs需要Python 3.6+；pdoc的最新公共版本仍然保持Python 2的兼容性。
• pdocs使用最新的开发工具以确保长期的可维护性（mypy、black、isort、flake8、bandit等）。
• 在本地服务时，pdocs将项目文档生成到临时文件夹中，而不是包含实时服务器。这是一种在简单性和性能之间的有意权衡。
• pdocs除了CLI API外，还提供简化的Python API。
• pdocs正在积极维护。
• pdocs使用hug CLI和子命令，pdoc使用argparse和单个命令。
• pdoc提供从命令行获取的文本文档，pdocs为了API的简单性移除了这个功能。

关于许可和分支的说明

原始的pdoc遵循Unlicense许可，因此这个分支的初始提交也遵循Unlicense许可在此处。Unlicense与MIT完全兼容，转向MIT的原因是MIT是一种更标准且更为人所知的许可。

如该提交所示，我选择创建一个新的分支以获得新的历史记录，因为该项目非常古老（2013年），并且我认为过去发生的许多提交可能由于Python生态系统自那时以来的许多变化，反而可能成为误导性的线索，而不是帮助调试问题。如果您出于任何原因希望查看完整的记录，它仍然可以在原始的pdoc存储库中找到。

为什么创建pdocs？

我创建pdocs是为了帮助portray，同时保持对原始pdoc愿景的忠诚，并保持MIT许可兼容性。最终，我创建它是为了帮助为Python项目提供更好的文档网站。

我希望您也觉得pdocs很有用！

~Timothy Crosley