我们应该使用Epydoc，Sphinx还是其他用于记录Python API的内容？ [英] Should we use Epydoc, Sphinx or something else for documenting Python APIs?

问题描述

我的团队需要一个工具来生成Python项目的API文档。我们之前已经使用过 Epydoc ，并且已经很开心了，但是这个项目似乎已经死了，最新的版本还没有与最新的docutils版本兼容。

My team needs a tool for generating API documentation for a Python project. We have previously used Epydoc, and have been pretty happy with it, but the project seems to be dead and the latest version isn't even compatible with the latest docutils releases.

似乎是我们有以下三个选项，你们推荐哪一个？

It seems to be that we have following three options, which one do you recommend?

1）继续使用Epydoc。这几乎需要我们分叉项目，使其与docutils兼容。所需的更改很简单 - 到目前为止，我们已经在本地修复了Epydoc，但是所有这些都需要一些工作，我们对维护Epydoc并不感兴趣。

1) Keep using Epydoc. This would pretty much require us to fork the project to make it compatible with docutils. The required changes are pretty trivial - so far we have fixed Epydoc locally - but all this requires some work and we aren't really interested in maintaining Epydoc.

2）开关狮身人面像。它是一般工程文档的一个很好的工具，但我不知道它是生成API文档的正确工具。事实上，我记得早先在Sphinx项目页面上看到一个注释，指出它不是一个API文档工具，而是应该使用Epydoc。我没有看到这样的一个音符，似乎情况已经改变了。我们已经使用了reStructuredText和Epydoc和我们的其他文档，所以切换到Sphinx可能不会太大的任务。

2) Switch to Sphinx. It is a great tool for general project documentation but I'm not sure is it the right tool for generating API documentation. In fact I remember seeing a note on the Sphinx project pages earlier stating that it isn't an API documentation tool and that Epydoc should be used for that instead. I don't see such a note anymore so it seems the situation has changed. We have used reStructuredText both with Epydoc and with our other documentation so switching to Sphinx probably wouldn't be too big a task.

3）完全使用其他东西。有没有其他的工具你会推荐用于Python API文档？

3) Use something else altogether. Is there some other tool you would recommend for Python API documentation?

推荐答案

虽然我没有亲自使用它，它看起来像狮身人面像 autosummary 扩展可能是您需要的。它提到它可以为autodoc扩展生成存根文件，实质上是自动生成api，尽管它看起来仍然需要一些手持，epydoc没有。

While I haven't used it personally, it looks like the Sphinx autosummary extension might what you need. It mentions it can generate stub files for the autodoc extension, essentially autogenerating the api, though it looks like it still requires some hand-holding which epydoc did not.

除了api-autogeneration问题，Sphinx绝对是要走的路 - 它在生成文档方面提供了极大的灵活性，并且拥有一些非常强大的api标记工具 autodoc extensions ， python语言域）。使我的公司从epydoc转移内部文档的主要原因是epydoc强制您按照名称排列图书馆的自顶向下的树视图;而Sphinx允许您以更符合逻辑的方式将其库的部分组合在一起，由其语义决定...不利的是，即使您只想使用epydoc的树形布局，也可以提供该结构。

The api-autogeneration issue aside, Sphinx is definitely the way to go - it offers a tremendous amount of flexibility in generating documentation, and has some very powerful api markup tools (autodoc extension, python language domain). The main thing that made my company switch our internal docs from epydoc was that epydoc forces you to have a top-down "tree" view of a library, sorted by name; whereas Sphinx allows you to group sections of your library's api in a more logical fashion determined by its semantics... the downside is it makes you provide that structure even if you just wanted to use epydoc's tree layout.

这篇关于我们应该使用Epydoc，Sphinx还是其他用于记录Python API的内容？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！