Python中是否有类似于Ruby的Yard的工具？

Question

我同时使用Python和Ruby，我非常喜欢Ruby的文档服务器Yard：

http://yardoc.org/

我想知道在Python世界中是否有类似的东西？"pydoc -p"已经很老旧、难看且不舒适，并且它似乎没有支持服务器模式的Sphinx和Epydoc。

你知道有什么类似的工具吗？

谢谢

- Kedare

---

我不知道Yard。你能解释一下Yard是做什么的，以及你期望从Python等效工具中得到哪些特性吗？ - Sven Marnach

Yard是一个文档服务器，当您安装它们时，它会自动生成gem（相当于egg）文档，并且还可以用作独立的文档生成器（如sphinx）。它提供了一个非常漂亮和现代化的Web界面，具有搜索、语法着色和类/模块树等功能。您可以在此处查看在线文档的示例：http://rubydoc.info/docs/yard/frames/file/docs/WhatsNew.md - Kedare

我正在寻找的功能是一个文档服务器，比pydoc -p更方便使用，能够让我在文档中搜索，并且有简单的导航方式（类似于Yard树）。 - Kedare

通过Sphinx生成文档后，您可以使用任何Web服务器来提供它。 它还具有“非常漂亮和现代化的Web界面，带有搜索、语法着色和类/模块树”。缺少什么？ 为什么“服务器模式”是如此重要的特性？ - Sven Marnach

这不是一个主要的功能，但在安装 gem 后立即获得文档而无需手动生成它是一个优点。 - Kedare

Sphinx 看起来很难用，只是为了生成 gem 文档... - Kedare

Answer 1

Python包没有一个固定的惯例来存放文档。一个包的主要文档可能会使用一系列不同的工具构建，有时基于docstrings，有时则不是。你在pydoc -p中看到的只是包内容和docstrings，而不是主要文档。如果这正是你想要的，你也可以使用Sphinx来完成此任务。这是我刚编写的一个shell脚本： sphinx-server

#!/bin/sh
sphinx-apidoc -F -o "$2" "$1"
cd "$2"
make html
cd _build/html
python -mSimpleHTTPServer 2345

将要查询信息的包的目录作为第一个参数，新文档生成目录作为第二个参数传入该函数。然后，将浏览器指向http://localhost:2345/

（注意：你可能需要从脚本中删除 Web 服务器调用。这只是为了演示目的。假设使用的是 Python 2.x）

- Sven Marnach

---

我在一个随机项目（SQLAlchemy）上尝试了这个，但我只得到了一个模块列表而没有任何文档，这正常吗？ - Kedare

@Kedare：我也在一个随机的包（标准库中的logging）上尝试了一下，对我来说它是有效的。该包应该以一种可以被Python导入的方式安装，并且您应该将Sphinx指向可以从该包导入的目录。Sphinx只能自动构建可以导入的模块的文档。 - Sven Marnach

好的，这是一个案例问题，我用包名称上的好案例再次尝试它，它可以工作 :) - Kedare

Answer 2

似乎没必要实现一个Web服务器来提供一些HTML。我倾向于喜欢*ix哲学，即每个工具只做好一件小事。不是说Web服务器很小。

但你可以看看http://docs.python.org/library/basehttpserver.html。

- user1277476