从 Python 文档字符串自动生成 GitHub Wiki 文档

Posted 2023-02-23

【中文标题】从 Python 文档字符串自动生成 GitHub Wiki 文档

【英文标题】：Automatically Generate GitHub Wiki Documentation from Python Docstrings

【发布时间】：2015-06-22 00:26:30

【问题描述】：

标题说明了一切。我想象的是为我的所有模块、类和函数提供文档字符串，并以某种方式通过 github（wiki？）很好地导航文档。此外，文档应该与最新代码同步，这意味着它应该在推送时更新/重新生成。这可能吗？

【问题讨论】：

Sphinx 绝对是它，尽管它使用 restructuredText 而不是 Markdown。对于 Markdown，有 mkdocs，但不支持文档字符串。虽然，我确实开始了这个实验（这可能是个坏主意）：github.com/waylan/mddoc

我遇到了同样的问题 (readme.md)，我不相信有一个很好的答案。我尝试了 mkdocs — 只是污染了我的文件夹 — 和 pydoc_markdown，这是 Google 的热门搜索，它只提供了 pydoc 提供的文本的一小部分。最后，我只是简单地得到了 pydoc 输出并进行了三四次搜索并替换了一些项目。

我们注意到 Github per-repo wiki 与主要 repo 提交无关，这意味着如果您想要准确的 per-commit 文档（以便任何签出的提交都有正确的文档对于它），per-repo wiki 是没用的。

是否可以展示一些最小的例子来说明你从什么开始以及你想要结束的 md？

【参考方案1】：

Pydoc 不会生成 markdown，它会生成一个临时文本标记，只是偶尔会碰巧匹配 markdown。您需要将 ad-hoc 文本转换为 markdown 转换器，这会失败很多，就像使用原始的 ad-hoc 文本一样，就好像它已经是 markdown 一样。

【参考方案2】：

只需将生成的docstring 的输出通过管道传输到.md 文件。

像这样：

pydoc example_lib > example_lib.md .