0

我们有一个 Python 项目，我们的文档目前分布在三个地方：我们有示例 Python 文件，我们有 Sphinx 文档（其中一些是从 IPython 笔记本生成的），我们有 IPython 笔记本。我们正在考虑将所有这些文档整合到一组 IPython 笔记本中。最终，我们希望通过将所有文档移动到一个地方并使用一个工具（IPython 笔记本），让我们的用户和开发人员的生活更轻松。而且，老实说，最大限度地减少维护文档所需的时间是这里的重中之重：所有开发人员都在空闲时间免费工作。

与 IPython 笔记本相比，Sphinx 的一大优势是 Sphinx 可以使用 apidoc 从代码中自动生成 API 文档。我的直觉是，应该可以通过编写一些遍历库的 python 文件的代码在 IPython 笔记本中复制这种行为，提取文档字符串以在笔记本中显示（包括渲染任何数学或图像以及文档字符串的相关部分（参数、返回值、注释等））。我的问题是：这样的工具是否已经存在？即一个可以遍历 Python 目录、提取文档字符串并将它们显示在 IPython 笔记本中的工具，最好使用漂亮的 HTML 格式？

4

1 回答 1

2

以下是您可能会发现有用的两个链接：

  • https://github.com/rossant/ipymd：这使您可以在 Markdown 文档上使用 IPython 笔记本前端。还有一个 md<->ipynb 转换 CLI 工具。在文档生成工具中处理 Markdown 文档比处理 ipynb 文件更容易。

  • https://github.com/kwikteam/phy/blob/master/tools/api.py：我编写的一个快速脚本，用于从 Python 项目中生成 Markdown 中的 API 文档。这里不涉及笔记本，但您可以使用 ipymd 将其转换为笔记本，或在笔记本前端进行编辑。

于 2015-06-09T10:07:01.677 回答